MCP Toolbox for Databases

Official

by googleapis

628 1.9k downloads Not rated yet Apache-2.0

GitHub Website

About

Provides a secure, configurable interface for executing pre-defined queries against multiple database systems including PostgreSQL, MySQL, SQL Server, Neo4j, Dgraph, and Spanner through a YAML-based configuration system.

Details

Repository: googleapis/mcp-toolbox
License: Apache-2.0

Explore

- Out‑of‑the‑box database access with prebuilt generic tools
- Custom tools framework for building safe, production‑ready tools
- Handles connection pooling, integrated auth (IAM), and OpenTelemetry
- Enhanced security with integrated authentication
- Simplified development (integrate in less than 10 lines of code)
- End‑to‑end observability with built‑in metrics and tracing

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name MCP Toolbox for Databases

Command (node, npx, python, etc.) npx
Arguments
- Argument 1 -y
- Argument 2 @toolbox-sdk/server
- Argument 3 --prebuilt=postgres
- Argument 4 --stdio
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

From the repository

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 query your data in plain English, automate schema discovery and management, and generate database-aware code.

You can use the Toolbox in any MCP-compatible IDE or client (e.g., Gemini CLI, Google Antigravity, Claude Code, Codex, etc.) by configuring the MCP server.

Prebuilt tools are also conveniently available via the Google Antigravity MCP Store with a simple click-to-install experience.

1. Add the following to your client's MCP configuration file (usually mcp.json or claude_desktop_config.json):

    {
      "mcpServers": {
        "toolbox-postgres": {
          "command": "npx",
          "args": [
            "-y",
            "@toolbox-sdk/server",
            "--prebuilt=postgres",
            "--stdio"
          ]
        }
      }
    }

2. Set the appropriate environment variables to connect, see the Prebuilt Tools Reference.

When you run Toolbox with a --prebuilt=<database> flag, you instantly get access to standard tools to interact with that database. You can also specify a specific toolset using the --prebuilt=<database>/<toolset> syntax (e.g., --prebuilt=postgres/data to only load SQL tools).

Supported databases currently include:
- Google Cloud: AlloyDB, BigQuery, Cloud SQL (PostgreSQL, MySQL, SQL Server), Spanner, Firestore, Knowledge Catalog (formerly known as Dataplex).
- Other Databases: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, MongoDB, Redis, Elasticsearch, CockroachDB, ClickHouse, Couchbase, Neo4j, Snowflake, Trino, and more.

For a full list of available tools and their capabilities across all supported databases, see the Prebuilt Tools Reference.

See the Install & Run the Toolbox server section for different execution methods like Docker or binaries.

> [!TIP]
> For users looking for a managed solution, Google Cloud MCP Servers
> provide a managed MCP experience with prebuilt tools; you can learn more about the differences here.

---

Toolbox can also be used as a framework for customized tools.
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 --config tools.yaml flag.

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

`list_tables`

List all the tables in the connected database.

`execute_sql`

Execute a raw SQL statement against the connected database. Parameters: sql (string)

`search-hotels-by-name`

Search for hotels based on name. Parameters: name (string) - The name of the hotel.

`skills-generate`

Convert a toolset into an Agent Skill compatible with the Agent Skill specification. Parameters: --name (string) - The name of the skill, --toolset (string) - The toolset to include, --description (string) - A description of the skill.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "mcp toolbox for databases": {
            "env": {},
            "args": [
                "-y",
                "@toolbox-sdk/server",
                "--prebuilt=postgres",
                "--stdio"
            ],
            "command": "npx"
        }
    }
}

Linux

{
    "env": [],
    "args": [
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=postgres",
        "--stdio"
    ],
    "command": "npx"
}

Macos

{
    "env": [],
    "args": [
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=postgres",
        "--stdio"
    ],
    "command": "npx"
}

Windows

{
    "env": [],
    "args": [
        "/c",
        "npx",
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=postgres",
        "--stdio"
    ],
    "command": "cmd"
}

Open source MCP server specializing in easy, fast, and secure tools for Databases.

What can you do with Toolbox For Databases MCP?

- Instant database exploration— Use prebuilt tools likelist_tablesandexecute_sqlto query your data in plain English from any MCP client.
- Custom SQL tools— Define parameterized SQL statements intools.yamlto expose safe, structured queries as MCP tools.
- Toolset grouping— Organize tools into namedtoolsetsto load only the relevant set for each agent or application.
- Reusable prompts— Definepromptsintools.yamlfor standardized LLM interactions like code review.

MCP Toolbox for Databases is an open source Model Context Protocol (MCP) server that connects your AI agents, IDEs, and applications directly to your enterprise databases.
- Ready-to-use MCP Server (Build-Time):Instantly connect Gemini CLI, Google Antigravity, Claude Code, Codex, or other MCP clients to your databases using ourprebuilt generic tools. Talk to your data, explore schemas, and generate code without writing boilerplate.
- Custom Tools Framework (Run-Time):A robust framework to build specialized, highly secure AI tools for your production agents. Define structured queries, semantic search, and NL2SQL capabilities safely and easily.

This README provides a brief overview. For comprehensive details, see thefull documentation.

[!IMPORTANT]
Repository Name Update:Thegenai-toolboxrepository has been officially renamed tomcp-toolbox. To ensure your local environment reflects the new name, you may update your remote:git remote set-url origin https://github.com/googleapis/mcp-toolbox.git

[!NOTE] This solution was originally named “Gen AI Toolbox for Databases” (github.com/googleapis/genai-toolbox) as its initial development predated MCP, but was renamed to align with the MCP compatibility.

- Why MCP Toolbox?
- Quick Start: Prebuilt Tools
- Quick Start: Custom Tools
- Install & Run the Toolbox server
- Connect to Toolbox

- MCP Client
- Toolbox SDKs: Integrate with your Application

- Out-of-the-Box Database Access:Prebuilt generic tools for instant data exploration (e.g.,list_tables,execute_sql) directly from your IDE or CLI.
- Custom Tools Framework:Build production-ready tools with your own predefined logic, ensuring safety through Restricted Access, Structured Queries, and Semantic Search.
- Simplified Development:Integrate tools into your Agent Development Kit (ADK), LangChain, LlamaIndex, or custom agents in less than 10 lines of code.
- Better Performance:Handles connection pooling, integrated auth (IAM), and end-to-end observability (OpenTelemetry) out of the box.
- Enhanced Security: Integrated authentication for more secure access to your data.
- End-to-end Observability: Out of the box metrics and tracing with built-in support for OpenTelemetry.

You can use the Toolbox in any MCP-compatible IDE or client (e.g., Gemini CLI, Google Antigravity, Claude Code, Codex, etc.) by configuring the MCP server.

Prebuilt tools are also conveniently available via theGoogle Antigravity MCP Storewith a simple click-to-install experience.
-

Add the following to your client's MCP configuration file (usuallymcp.jsonorclaude_desktop_config.json):

{ "mcpServers": { "toolbox-postgres": { "command": "npx", "args": [ "-y", "@toolbox-sdk/server", "--prebuilt=postgres", "--stdio" ] } } }

Set the appropriate environment variables to connect, see thePrebuilt Tools Reference.

When you run Toolbox with a--prebuilt=<database>flag, you instantly get access to standard tools to interact with that database. You can also specify a specific toolset using the--prebuilt=<database>/<toolset>syntax (e.g.,--prebuilt=postgres/datato only load SQL tools).

- Google Cloud:AlloyDB, BigQuery, Cloud SQL (PostgreSQL, MySQL, SQL Server), Spanner, Firestore, Knowledge Catalog (formerly known as Dataplex).
- Other Databases:PostgreSQL, MySQL,MariaDB, SQL Server, Oracle, MongoDB, Redis, Elasticsearch, CockroachDB, ClickHouse, Couchbase, Neo4j, Snowflake, Trino, and more.

For a full list of available tools and their capabilities across all supported databases, see the Prebuilt Tools Reference.

See theInstall & Run the Toolbox serversection for different execution methods like Docker or binaries.

[!TIP] For users looking for a managed solution,Google Cloud MCP Serversprovide a managed MCP experience with prebuilt tools; you can learn more about the differences here.

Toolbox can also be used as a framework for customized tools. The primary way to configure Toolbox is through thetools.yamlfile. If you have multiple files, you can tell Toolbox which to load with the--config tools.yamlflag.

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

Thesourcessection of yourtools.yamldefines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against.

kind: source 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.

Thetoolssection of atools.yamldefine the actions an agent can take: what type of tool it is, which source(s) it affects, what parameters it uses, etc.

kind: tool 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.

Thetoolsetssection of yourtools.yamlallows 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.

kind: toolset name: my_first_toolset tools: - my_first_tool - my_second_tool --- kind: toolset name: my_second_toolset tools: - my_second_tool - my_third_tool

Thepromptssection of atools.yamldefines prompts that can be used for interactions with LLMs.

kind: prompt name: 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.

You can run Toolbox directly with a configuration file:

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

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

[!NOTE] This method is optimized for convenience rather than performance. For a more standard and reliable installation, please use the binary or container image as described inInstall & Run the Toolbox server.

For the latest version, check the releases pageand use the following instructions for your OS and CPU architecture.Linux (AMD64)

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

# see releases page for other versions export VERSION=1.9.0 curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/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=1.9.0 curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/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=1.9.0 curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/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=1.9.0 curl -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v%VERSION%/windows/amd64/toolbox.exe"

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

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

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

:: see releases page for other versions set VERSION=1.9.0 curl -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v%VERSION%/windows/arm64/toolbox.exe"

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

# see releases page for other versions $VERSION = "1.9.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/arm64/toolbox.exe"

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

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:

go install github.com/googleapis/[email protected]

# Install Gemini CLI npm install -g @google/gemini-cli # Install the extension gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgres # Run Gemini CLI gemini

Interact with your custom tools using natural language through the Gemini CLI.

# Install the extension gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

Configureatools.yamlto define your tools, and then executetoolboxto start the server:

./toolbox --config "tools.yaml"

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

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 \ --config "/app/tools.yaml"

ⓘ Note
The-vflag mounts your localtools.yamlinto the container, and-pmaps the container's port5000to your host's port5000.

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 doesnotcompile a binary into your$GOPATH. If you want to compile a binary instead, refer the Developer Documentation.

If you installed Toolbox using Homebrew, thetoolboxbinary 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):

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

# Run Gemini CLI gemini # List extensions /extensions list # List MCP servers /mcp list

You can usetoolbox helpfor a full list of flags! To stop the server, send a terminate signal (ctrl+con most platforms).

For more detailed documentation on deploying to different environments, check out the resources in the Deploy Toolbox section

Once your Toolbox server is up and running, you can load tools into your MCP-compatible client or application.

Add the following configuration to your MCP client configuration:

{ "mcpServers": { "toolbox": { "type": "http", "url": "http://127.0.0.1:5000/mcp", } } }

If you would like to connect to a specific toolset, replace url with "http://127.0.0.1:5000/mcp/{toolset_name}".

Toolbox SDKs: Integrate with your Application

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

MCP Toolbox for Databases

About

Details

Explore

Setting up with Highlight

Setting up with Cursor

JSON

JSON

JSON

Setting up with Claude Desktop

JSON

JSON

JSON

Setting up with Windsurf

JSON

JSON

JSON

Setting up with Cline

JSON

JSON

JSON

Setting up with Goose

JSON

JSON

JSON

From the repository

`list_tables`

`execute_sql`

`search-hotels-by-name`

`skills-generate`

Claude Desktop / Cursor

Linux

Macos

Windows

What can you do with Toolbox For Databases MCP?

Toolbox SDKs: Integrate with your Application

Videos about MCP Toolbox for Databases

Google Cloud Live: Getting started with MCP Toolbox for Databases

[Github] googleapis/genai-toolbox - MCP Toolbox for Databases

Build an AI That Connects to Your Database | MCP Toolbox for Databases Course (Introduction)

About

Details

Explore

Setting up with Highlight

From the repository

list_tables

execute_sql

search-hotels-by-name

skills-generate

Claude Desktop / Cursor

Linux

Macos

Windows

What can you do with Toolbox For Databases MCP?

Videos about MCP Toolbox for Databases

More like this

`list_tables`

`execute_sql`

`search-hotels-by-name`

`skills-generate`