MCP Toolbox for Databases

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.

Table of Contents

• 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 , 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 .

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

(Non-production) Running Toolbox

You can run Toolbox directly with a configuration file:

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

Installing the server

For the latest version, check the and use the following instructions for your OS and CPU architecture.

To install Toolbox as a binary:

To install Toolbox as a binary on Linux (AMD64):

# see releases page for other versions export VERSION=0.24.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox

To install Toolbox as a binary on macOS (Apple Silicon):

# see releases page for other versions export VERSION=0.24.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox chmod +x toolbox

To install Toolbox as a binary on macOS (Intel):

# see releases page for other versions export VERSION=0.24.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox chmod +x toolbox

To install Toolbox as a binary on Windows (Command Prompt):

:: see releases page for other versions set VERSION=0.24.0 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe"

To install Toolbox as a binary on Windows (PowerShell):

# see releases page for other versions $VERSION = "0.24.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe"

To install Toolbox using Homebrew on macOS or Linux:

To install from source, ensure you have the latest version of Go installed, and then run the following command:

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

Running the server

Configure a tools.yaml to define your tools, and then execute toolbox to start the server:

To run Toolbox from binary:

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

To run the server after pulling the container image:

ⓘ 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.

To run the server directly from source, navigate to the project root directory and 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.

If you installed Toolbox using Homebrew, the toolbox binary is available in your system path. You can start the server with the same command:

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

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

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:

1. Install :

   pip install toolbox-core

2. Load tools:

   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 .

1. Install :

   pip install toolbox-langchain

2. Load tools:

   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 .

1. Install :

   pip install toolbox-llamaindex

2. Load tools:

   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 .

1. Install :

   npm install @toolbox-sdk/core

2. Load tools:

   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 .

1. Install :

   npm install @toolbox-sdk/core

2. Load tools:

   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);

1. Install :

   npm install @toolbox-sdk/core

2. Load tools:

   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);

1. Install :

   npm install @toolbox-sdk/adk

2. Load tools:

   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 .

1. Install :

   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 .

1. Install :

   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, }, } }

1. Install :

   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()) }

1. Install :

   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}, } }

1. Install :

   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, }, } }

1. Install :

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

2. 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 .

Using Toolbox with 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 with Gemini CLI:

• AlloyDB for PostgreSQL

• AlloyDB for PostgreSQL Observability

• BigQuery Data Analytics

• BigQuery Conversational Analytics

• Cloud SQL for MySQL

• Cloud SQL for MySQL Observability

• Cloud SQL for PostgreSQL

• Cloud SQL for PostgreSQL Observability

• Cloud SQL for SQL Server

• Cloud SQL for SQL Server Observability

• Looker

• Dataplex

• MySQL

• PostgreSQL

• Spanner

• Firestore

• SQL Server

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.

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 kind of tool it is, which source(s) it affects, what parameters it uses, etc.

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.

You can load toolsets by name:

Prompts

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

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 versioning will follow the more common convention:

• MAJOR.MINOR.PATCH: Incremented for incompatible API changes.

• MAJOR.MINOR.PATCH: Incremented for new, backward-compatible functionality.

• MAJOR.MINOR.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.

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!