MCP Toolbox for Databases

<a href="https://trendshift.io/repositories/13019" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13019" alt="googleapis%2Fgenai-toolbox | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

[!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.

[!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.

<!-- TOC ignore:true -->

Table of Contents

<!-- TOC -->

• 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

<!-- /TOC -->

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.

<p align="center"> <img src="./docs/en/getting-started/introduction/architecture.png" alt="architecture" width="50%"/> </p>

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

<details open> <summary>Binary</summary>

To install Toolbox as a binary:

<!-- {x-release-please-start-version} -->

<details> <summary>Linux (AMD64)</summary>

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

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

</details> <details> <summary>macOS (Apple Silicon)</summary>

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

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

</details> <details> <summary>macOS (Intel)</summary>

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

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

</details> <details> <summary>Windows (Command Prompt)</summary>

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

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

</details> <details> <summary>Windows (PowerShell)</summary>

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

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

</details>

</details> <details> <summary>Container image</summary> You can also install Toolbox as a container:

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

</details> <details> <summary>Homebrew</summary>

To install Toolbox using Homebrew on macOS or Linux:

brew install mcp-toolbox

</details> <details> <summary>Compile from source</summary>

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

<!-- {x-release-please-end} --> </details> <details> <summary>Gemini CLI Extensions</summary>

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

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

</details>

Running the server

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

<details open> <summary>Binary</summary>

To run Toolbox from binary:

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

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

</details> <details> <summary>Container image</summary>

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.

</details> <details> <summary>Source</summary>

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.

</details> <details> <summary>Homebrew</summary>

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"

</details> <details> <

---