MCP Toolbox for Databases

[!NOTE]
MCP Toolbox for Databases is currently in beta, and may see breaking
changes until the first stable release (v1.0).

MCP Toolbox for Databases is an open source MCP server for databases. It enables

you to develop tools easier, faster, and more securely by handling the complexities

such as connection pooling, authentication, and more.

This README provides a brief overview. For comprehensive details, see the [full

documentation](https://googleapis.github.io/genai-toolbox/).

[!NOTE]
This solution was originally named “Gen AI Toolbox for Databases” as
its initial development predated MCP, but was renamed to align with recently
added MCP compatibility.

Why Toolbox?
General Architecture
Getting Started
Installing the server
Running the server
Integrating your application
Using Toolbox with Gemini CLI Extensions
Configuration
Sources
Tools
Toolsets
Prompts
Versioning
Pre-1.0.0 Versioning
Post-1.0.0 Versioning
Contributing
Community

Why Toolbox?

Toolbox helps you build Gen AI tools that let your agents access data in your

database. Toolbox provides:

Simplified development: Integrate tools to your agent in less than 10

lines of code, reuse tools between multiple agents or frameworks, and deploy

new versions of tools more easily.

Better performance: Best practices such as connection pooling,

authentication, and more.

Enhanced security: Integrated auth for more secure access to your data
End-to-end observability: Out of the box metrics and tracing with built-in

support for OpenTelemetry.

⚡ Supercharge Your Workflow with an AI Database Assistant ⚡

Stop context-switching and let your AI assistant become a true co-developer. By

connecting your IDE to your databases with MCP Toolbox, you can

delegate complex and time-consuming database tasks, allowing you to build faster

and focus on what matters. This isn't just about code completion; it's about

giving your AI the context it needs to handle the entire development lifecycle.

Here’s how it will save you time:

Query in Plain English: Interact with your data using natural language

right from your IDE. Ask complex questions like, *"How many orders were

delivered in 2024, and what items were in them?"* without writing any SQL.

Automate Database Management: Simply describe your data needs, and let the

AI assistant manage your database for you. It can handle generating queries,

creating tables, adding indexes, and more.

Generate Context-Aware Code: Empower your AI assistant to generate

application code and tests with a deep understanding of your real-time

database schema. This accelerates the development cycle by ensuring the

generated code is directly usable.

Slash Development Overhead: Radically reduce the time spent on manual

setup and boilerplate. MCP Toolbox helps streamline lengthy database

configurations, repetitive code, and error-prone schema migrations.

Learn how to connect your AI tools (IDEs) to Toolbox using MCP.

General Architecture

Toolbox sits between your application's orchestration framework and your

database, providing a control plane that is used to modify, distribute, or

invoke tools. It simplifies the management of your tools by providing you with a

centralized location to store and update tools, allowing you to share tools

between agents and applications and update those tools without necessarily

redeploying your application.

Getting Started

Quickstart: Running Toolbox using NPX

You can run Toolbox directly with a configuration file:

npx @toolbox-sdk/server --tools-file tools.yaml

This runs the latest version of the toolbox server with your configuration file.

[!NOTE]
This method should only be used for non-production use cases such as
experimentation. For any production use-cases, please consider [Installing the
server](#installing-the-server) and then running it.

Installing the server

For the latest version, check the releases page and use the

following instructions for your OS and CPU architecture.

Binary

To install Toolbox as a binary:

Linux (AMD64)
To install Toolbox as a binary on Linux (AMD64):
```sh
# see releases page for other versions
export VERSION=0.29.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
```
macOS (Apple Silicon)
To install Toolbox as a binary on macOS (Apple Silicon):
```sh
# see releases page for other versions
export VERSION=0.29.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox
chmod +x toolbox
```
macOS (Intel)
To install Toolbox as a binary on macOS (Intel):
```sh
# see releases page for other versions
export VERSION=0.29.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox
chmod +x toolbox
```
Windows (Command Prompt)
To install Toolbox as a binary on Windows (Command Prompt):
```cmd
:: see releases page for other versions
set VERSION=0.29.0
curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe"
```
Windows (PowerShell)
To install Toolbox as a binary on Windows (PowerShell):
```powershell
# see releases page for other versions
$VERSION = "0.29.0"
curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe"
```

Container image

You can also install Toolbox as a container:

# see releases page for other versions
export VERSION=0.29.0
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION

Homebrew

To install Toolbox using Homebrew on macOS or Linux:

brew install mcp-toolbox

Compile from source

To install from source, ensure you have the latest version of

Go installed, and then run the following command:

go install github.com/googleapis/genai-toolbox@v0.29.0

Gemini CLI Extensions

To install Gemini CLI Extensions for MCP Toolbox, run the following command:

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

Running the server

Configure a tools.yaml to define your tools, and then

execute toolbox to start the server:

Binary

To run Toolbox from binary:

./toolbox --tools-file "tools.yaml"

ⓘ Note
Toolbox enables dynamic reloading by default. To disable, use the
--disable-reload flag.

Container image

To run the server after pulling the container image:

export VERSION=0.24.0 # Use the version you pulled
docker run -p 5000:5000 \
-v $(pwd)/tools.yaml:/app/tools.yaml \
us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
--tools-file "/app/tools.yaml"

ⓘ Note
The -v flag mounts your local tools.yaml into the container, and -p maps
the container's port 5000 to your host's port 5000.

Source

To run the server directly from source, navigate to the project root directory

and run:

go run .

ⓘ Note
This command runs the project from source, and is more suitable for development
and testing. It does not compile a binary into your $GOPATH. If you want
to compile a binary instead, refer the [Developer
Documentation](./DEVELOPER.md#building-the-binary).

Homebrew

If you installed Toolbox using Homebrew, the toolbox

binary is available in your system path. You can start the server with the same

command:

toolbox --tools-file "tools.yaml"

NPM

To run Toolbox directly without manually downloading the binary (requires Node.js):

npx @toolbox-sdk/server --tools-file tools.yaml

Gemini CLI

Interact with your custom tools using natural language. Check

gemini-cli-extensions/mcp-toolbox

for more information.

You can use toolbox help for a full list of flags! To stop the server, send a

terminate signal (ctrl+c on most platforms).

For more detailed documentation on deploying to different environments, check

out the resources in the [How-to

section](https://googleapis.github.io/genai-toolbox/how-to/)

Integrating your application

Once your server is up and running, you can load the tools into your

application. See below the list of Client SDKs for using various frameworks:

Python ()

Core

1. Install Toolbox Core SDK:

bash

pip install toolbox-core

1. Load tools:

python

from toolbox_core import ToolboxClient

    # update the url to point to your server
    async with ToolboxClient("http://127.0.0.1:5000") as client:

        # these tools can be passed to your application!
        tools = await client.load_toolset("toolset_name")

For more detailed instructions on using the Toolbox Core SDK, see the

project's README.

LangChain / LangGraph

1. Install Toolbox LangChain SDK:

bash

pip install toolbox-langchain

1. Load tools:

python

from toolbox_langchain import ToolboxClient

    # update the url to point to your server
    async with ToolboxClient("http://127.0.0.1:5000") as client:

        # these tools can be passed to your application!
        tools = client.load_toolset()

For more detailed instructions on using the Toolbox LangChain SDK, see the

project's README.

[toolbox-langchain]: https://pypi.org/project/toolbox-langchain/

[toolbox-langchain-readme]: https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md

LlamaIndex

1. Install Toolbox Llamaindex SDK:

bash

pip install toolbox-llamaindex

1. Load tools:

python

from toolbox_llamaindex import ToolboxClient

    # update the url to point to your server
    async with ToolboxClient("http://127.0.0.1:5000") as client:

        # these tools can be passed to your application!
        tools = client.load_toolset()

For more detailed instructions on using the Toolbox Llamaindex SDK, see the

project's README.

[toolbox-llamaindex]: https://pypi.org/project/toolbox-llamaindex/

[toolbox-llamaindex-readme]: https://github.com/googleapis/genai-toolbox-llamaindex-python/blob/main/README.md

Javascript/Typescript ()

Core

1. Install Toolbox Core SDK:

bash

npm install @toolbox-sdk/core

1. Load tools:

javascript

import { ToolboxClient } from '@toolbox-sdk/core';

    // update the url to point to your server
    const URL = 'http://127.0.0.1:5000';
    let client = new ToolboxClient(URL);

    // these tools can be passed to your application!
    const tools = await client.loadToolset('toolsetName');

For more detailed instructions on using the Toolbox Core SDK, see the

project's README.

[toolbox-core-js]: https://www.npmjs.com/package/@toolbox-sdk/core

[toolbox-core-js-readme]: https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md

LangChain / LangGraph

1. Install Toolbox Core SDK:

bash

npm install @toolbox-sdk/core

2. Load tools:

javascript

import { ToolboxClient } from '@toolbox-sdk/core';

    // update the url to point to your server
    const URL = 'http://127.0.0.1:5000';
    let client = new ToolboxClient(URL);

    // these tools can be passed to your application!
    const toolboxTools = await client.loadToolset('toolsetName');

    // Define the basics of the tool: name, description, schema and core logic
    const getTool = (toolboxTool) => tool(currTool, {
        name: toolboxTool.getName(),
        description: toolboxTool.getDescription(),
        schema: toolboxTool.getParamSchema()
    });

    // Use these tools in your Langchain/Langraph applications
    const tools = toolboxTools.map(getTool);

Genkit

1. Install Toolbox Core SDK:

bash

npm install @toolbox-sdk/core

2. Load tools:

javascript

import { ToolboxClient } from '@toolbox-sdk/core';
    import { genkit } from 'genkit';

    // Initialise genkit
    const ai = genkit({
        plugins: [
            googleAI({
                apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY
            })
        ],
        model: googleAI.model('gemini-2.0-flash'),
    });

    // update the url to point to your server
    const URL = 'http://127.0.0.1:5000';
    let client = new ToolboxClient(URL);

    // these tools can be passed to your application!
    const toolboxTools = await client.loadToolset('toolsetName');

    // Define the basics of the tool: name, description, schema and core logic
    const getTool = (toolboxTool) => ai.defineTool({
        name: toolboxTool.getName(),
        description: toolboxTool.getDescription(),
        schema: toolboxTool.getParamSchema()
    }, toolboxTool)

    // Use these tools in your Genkit applications
    const tools = toolboxTools.map(getTool);

ADK

1. Install Toolbox ADK SDK:

bash

npm install @toolbox-sdk/adk

2. Load tools:

javascript

import { ToolboxClient } from '@toolbox-sdk/adk';

    // update the url to point to your server
    const URL = 'http://127.0.0.1:5000';
    let client = new ToolboxClient(URL);

    // these tools can be passed to your application!
    const tools = await client.loadToolset('toolsetName');

For more detailed instructions on using the Toolbox ADK SDK, see the

project's README.

[toolbox-adk-js]: https://www.npmjs.com/package/@toolbox-sdk/adk

[toolbox-adk-js-readme]:

https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-adk/README.md

Go ()

Core

1. Install Toolbox Go SDK:

bash

go get github.com/googleapis/mcp-toolbox-sdk-go

2. Load tools:

package main

    import (
      "github.com/googleapis/mcp-toolbox-sdk-go/core"
      "context"
    )

    func main() {
      // Make sure to add the error checks
      // update the url to point to your server
      URL := "http://127.0.0.1:5000";
      ctx := context.Background()

      client, err := core.NewToolboxClient(URL)

      // Framework agnostic tools
      tools, err := client.LoadToolset("toolsetName", ctx)
    }

For more detailed instructions on using the Toolbox Go SDK, see the

project's README.

[toolbox-go]: https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core

[toolbox-core-go-readme]: https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md

LangChain Go

1. Install Toolbox Go SDK:

bash

go get github.com/googleapis/mcp-toolbox-sdk-go

2. Load tools:

package main

    import (
      "context"
      "encoding/json"

      "github.com/googleapis/mcp-toolbox-sdk-go/core"
      "github.com/tmc/langchaingo/llms"
    )

    func main() {
      // Make sure to add the error checks
      // update the url to point to your server
      URL := "http://127.0.0.1:5000"
      ctx := context.Background()

      client, err := core.NewToolboxClient(URL)

      // Framework agnostic tool
      tool, err := client.LoadTool("toolName", ctx)

      // Fetch the tool's input schema
      inputschema, err := tool.InputSchema()

      var paramsSchema map[string]any
      _ = json.Unmarshal(inputschema, &paramsSchema)

      // Use this tool with LangChainGo
      langChainTool := llms.Tool{
        Type: "function",
        Function: &llms.FunctionDefinition{
          Name:        tool.Name(),
          Description: tool.Description(),
          Parameters:  paramsSchema,
        },
      }
    }

Genkit

1. Install Toolbox Go SDK:

bash

go get github.com/googleapis/mcp-toolbox-sdk-go

2. Load tools:

package main
    import (
      "context"
      "log"

      "github.com/firebase/genkit/go/genkit"
      "github.com/googleapis/mcp-toolbox-sdk-go/core"
      "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit"
    )

    func main() {
      // Make sure to add the error checks
      // Update the url to point to your server
      URL := "http://127.0.0.1:5000"
      ctx := context.Background()
      g := genkit.Init(ctx)

      client, err := core.NewToolboxClient(URL)

      // Framework agnostic tool
      tool, err := client.LoadTool("toolName", ctx)

      // Convert the tool using the tbgenkit package
      // Use this tool with Genkit Go
      genkitTool, err := tbgenkit.ToGenkitTool(tool, g)
      if err != nil {
        log.Fatalf("Failed to convert tool: %v\n", err)
      }
      log.Printf("Successfully converted tool: %s", genkitTool.Name())
    }

Go GenAI

1. Install Toolbox Go SDK:

bash

go get github.com/googleapis/mcp-toolbox-sdk-go

2. Load tools:

package main

    import (
      "context"
      "encoding/json"

      "github.com/googleapis/mcp-toolbox-sdk-go/core"
      "google.golang.org/genai"
    )

    func main() {
      // Make sure to add the error checks
      // Update the url to point to your server
      URL := "http://127.0.0.1:5000"
      ctx := context.Background()

      client, err := core.NewToolboxClient(URL)

      // Framework agnostic tool
      tool, err := client.LoadTool("toolName", ctx)

      // Fetch the tool's input schema
      inputschema, err := tool.InputSchema()

      var schema *genai.Schema
      _ = json.Unmarshal(inputschema, &schema)

      funcDeclaration := &genai.FunctionDeclaration{
        Name:        tool.Name(),
        Description: tool.Description(),
        Parameters:  schema,
      }

      // Use this tool with Go GenAI
      genAITool := &genai.Tool{
        FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration},
      }
    }

OpenAI Go

1. Install Toolbox Go SDK:

bash

go get github.com/googleapis/mcp-toolbox-sdk-go

2. Load tools:

package main

    import (
      "context"
      "encoding/json"

      "github.com/googleapis/mcp-toolbox-sdk-go/core"
      openai "github.com/openai/openai-go"
    )

    func main() {
      // Make sure to add the error checks
      // Update the url to point to your server
      URL := "http://127.0.0.1:5000"
      ctx := context.Background()

      client, err := core.NewToolboxClient(URL)

      // Framework agnostic tool
      tool, err := client.LoadTool("toolName", ctx)

      // Fetch the tool's input schema
      inputschema, err := tool.InputSchema()

      var paramsSchema openai.FunctionParameters
      _ = json.Unmarshal(inputschema, &paramsSchema)

      // Use this tool with OpenAI Go
      openAITool := openai.ChatCompletionToolParam{
        Function: openai.FunctionDefinitionParam{
          Name:        tool.Name(),
          Description: openai.String(tool.Description()),
          Parameters:  paramsSchema,
        },
      }

    }

ADK Go

1. Install Toolbox Go SDK:

bash

go get github.com/googleapis/mcp-toolbox-sdk-go

1. Load tools:

package main

    import (
      "github.com/googleapis/mcp-toolbox-sdk-go/tbadk"
      "context"
    )

    func main() {
      // Make sure to add the error checks
      // Update the url to point to your server
      URL := "http://127.0.0.1:5000"
      ctx := context.Background()
      client, err := tbadk.NewToolboxClient(URL)
      if err != nil {
        return fmt.Sprintln("Could not start Toolbox Client", err)
      }

      // Use this tool with ADK Go
      tool, err := client.LoadTool("toolName", ctx)
      if err != nil {
        return fmt.Sprintln("Could not load Toolbox Tool", err)
      }
    }

For more detailed instructions on using the Toolbox Go SDK, see the

project's README.

Using Toolbox with Gemini CLI Extensions

Gemini CLI extensions provide tools to interact

directly with your data sources from command line. Below is a list of Gemini CLI

extensions that are built on top of Toolbox. They allow you to interact with

your data sources through pre-defined or custom tools with natural language.

Click into the link to see detailed instructions on their usage.

To use custom tools with Gemini CLI:

MCP Toolbox

To use prebuilt tools with Gemini CLI:

AlloyDB for PostgreSQL
[AlloyDB for PostgreSQL

Observability](https://github.com/gemini-cli-extensions/alloydb-observability)

[BigQuery Data

Analytics](https://github.com/gemini-cli-extensions/bigquery-data-analytics)

[BigQuery Conversational

Analytics](https://github.com/gemini-cli-extensions/bigquery-conversational-analytics)

[Cloud SQL for

MySQL](https://github.com/gemini-cli-extensions/cloud-sql-mysql)

[Cloud SQL for MySQL

Observability](https://github.com/gemini-cli-extensions/cloud-sql-mysql-observability)

[Cloud SQL for

PostgreSQL](https://github.com/gemini-cli-extensions/cloud-sql-postgresql)

[Cloud SQL for PostgreSQL

Observability](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability)

[Cloud SQL for SQL

Server](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver)

[Cloud SQL for SQL Server

Observability](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability)

Configuration

The primary way to configure Toolbox is through the tools.yaml file. If you

have multiple files, you can tell toolbox which to load with the `--tools-file

tools.yaml` flag.

You can find more detailed reference documentation to all resource types in the

Resources.

Sources

The sources section of your tools.yaml defines what data sources your

Toolbox should have access to. Most tools will have at least one source to

execute against.

yaml

kind: sources
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: toolbox_user
password: my-password

For more details on configuring different types of sources, see the

Sources.

Tools

The tools section of a tools.yaml define the actions an agent can take: what

type of tool it is, which source(s) it affects, what parameters it uses, etc.

yaml

kind: tools
name: search-hotels-by-name
type: postgres-sql
source: my-pg-source
description: Search for hotels based on name.
parameters:
  - name: name
    type: string
    description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';

For more details on configuring different types of tools, see the

Tools.

Toolsets

The toolsets section of your tools.yaml allows you to define groups of tools

that you want to be able to load together. This can be useful for defining

different groups based on agent or application.

yaml

toolsets:
    my_first_toolset:
        - my_first_tool
        - my_second_tool
    my_second_toolset:
        - my_second_tool
        - my_third_tool

You can load toolsets by name:

python

# This will load all tools
all_tools = client.load_toolset()

# This will only load the tools listed in 'my_second_toolset'
my_second_toolset = client.load_toolset("my_second_toolset")

Prompts

The prompts section of a tools.yaml defines prompts that can be used for

interactions with LLMs.

yaml

prompts:
  code_review:
    description: "Asks the LLM to analyze code quality and suggest improvements."
    messages:
      - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}"
    arguments:
      - name: "code"
        description: "The code to review"

For more details on configuring prompts, see the

Prompts.

Versioning

This project uses semantic versioning (MAJOR.MINOR.PATCH).

Since the project is in a pre-release stage (version 0.x.y), we follow the

standard conventions for initial development:

Pre-1.0.0 Versioning

While the major version is 0, the public API should be considered unstable.

The version will be incremented as follows:

**0.MINOR.PATCH: The MINOR** version is incremented when we add

new functionality or make breaking, incompatible API changes.

**0.MINOR.PATCH: The PATCH** version is incremented for

backward-compatible bug fixes.

Post-1.0.0 Versioning

Once the project reaches a stable 1.0.0 release, the version number

**MAJOR.MINOR.PATCH** will follow the more common convention:

**MAJOR**: Incremented for incompatible API changes.
**MINOR**: Incremented for new, backward-compatible functionality.
**PATCH**: Incremented for backward-compatible bug fixes.

The public API that this applies to is the CLI associated with Toolbox, the

interactions with official SDKs, and the definitions in the tools.yaml file.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING

to get started. For technical details on setting up your development

environment, see the DEVELOPER guide.

Please note that this project is released with a Contributor Code of Conduct.

By participating in this project you agree to abide by its terms. See

Contributor Code of Conduct for more information.

Community

Join our discord community to connect with our developers!

Genai Toolbox

Documentation

MCP Toolbox for Databases

Table of Contents

Why Toolbox?

General Architecture

Getting Started

Quickstart: Running Toolbox using NPX

Installing the server

Running the server

Integrating your application

Using Toolbox with Gemini CLI Extensions

Configuration

Sources

Tools

Toolsets

Prompts

Versioning

Pre-1.0.0 Versioning

Post-1.0.0 Versioning

Contributing

Community

Similar MCP

Mcpjungle

Anyquery

Yutu

Mcp Cyclops

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Mcpjungle

Anyquery

Yutu

Mcp Cyclops

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare