googleapis/mcp-toolbox

What It Does

MCP Toolbox for Databases is the official Google MCP server for database access, published by the googleapis org (the same group that maintains the Google Cloud SDKs). It is a single Go binary that exposes enterprise databases to AI agents over the Model Context Protocol, and it serves two distinct jobs at once. As a ready-to-use MCP server, it ships 35 prebuilt configurations that give an IDE or CLI immediate access to a database (execute_sql, list_tables) with zero YAML authoring. As a custom-tools framework, it lets you write a tools.yaml that defines parameterized SQL statements, semantic-search bindings, and NL2SQL endpoints, and the server compiles each entry into a typed MCP tool with JSON Schema input validation, an annotations block, and bound connection pooling.

The server speaks both MCP transports that matter (--stdio for local-agent integrations, default streamable-http on port 5000 for remote clients), supports four MCP protocol versions (2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25) plus an opt-in --enable-draft-specs for upcoming drafts, and ships first-party SDKs in Python (toolbox-core), TypeScript (@toolbox-sdk/core), Go (mcp-toolbox-sdk-go), and Java (mcp-toolbox-sdk-java). It also includes a skills-generate subcommand that emits a SKILL.md plus Node.js wrapper scripts directly from a tool config, which is the surface that earns it a GearScope review. The targets are developers building coding agents, conversational assistants, or autonomous workflows that need to read or write to a real database. The repo is 15,979 stars, 1,641 forks, 247 open issues, 2 years old, and pushed to within the last 24 hours.

The Good

The breadth of first-party database coverage is unmatched in the MCP ecosystem. The internal/sources/ directory contains 47 source connectors: AlloyDB (Postgres and admin), BigQuery, Bigtable, Cloud SQL (Postgres, MySQL, SQL Server, plus admin and observability variants), Cloud Storage, Spanner (incl. Postgres dialect), Firestore, Looker, Knowledge Catalog (Dataplex), Dataproc, plus the open-source tier (Postgres, MySQL, MongoDB, Redis, Elasticsearch, Snowflake, Oracle, MS SQL, ClickHouse, CockroachDB, Couchbase, Neo4j, Cassandra, ScyllaDB, SingleStore, Trino, Dgraph, Valkey, Firebird, OceanBase, YugabyteDB, TiDB, MindsDB, Arcadedb, SQL Server). At 15,979 stars it is the largest official-vendor agent-infrastructure repo GearScope had not reviewed, and no other first-party cloud org ships this many database connectors under one MCP server. For a coding agent that needs to query whatever database a project happens to use, this is the broadest single-binary surface in the ecosystem.

The full MCP protocol path works end-to-end on a real database. I installed the Python wrapper (pip3 install toolbox-server), created a SQLite database with three hotel rows, wrote a 30-line tools.yaml with one unparameterized and one parameterized tool, started the server on port 5099, and exercised every MCP method. initialize returned protocolVersion: 2025-03-26, capabilities: {tools, prompts}, and the correct serverInfo. tools/list returned both tools with valid JSON Schema inputSchema, the required-parameters array, and the MCP annotations block (readOnlyHint, destructiveHint). tools/call list-hotels returned all three real hotel rows as JSON-per-row text content. tools/call find-hotel-by-city {city:"New York"} with the SQLite ? placeholder correctly bound the parameter and returned only the Marriott NYC row. The CLI invoke subcommand produced the same output without needing an MCP client. This is a working MCP server backed by a real database, not a README claim.

The skills-generate command emits a correct, installable SKILL.md. The headline feature for the agent-skill ecosystem is real. toolbox skills-generate --config tools.yaml --name hotel-lookup --description "..." --toolset hotels-set --output-dir ./generated-skills produced generated-skills/hotel-lookup/SKILL.md with valid YAML frontmatter (name:, description:), a Usage section with Bash and PowerShell invocation patterns, and a per-tool reference with a Markdown parameter table (Name, Type, Description, Required, Default). It also emitted two Node.js wrapper scripts in scripts/ that re-invoke the toolbox binary against the embedded config, plus a copy of the source YAML in assets/. The output is a clean, progressive-disclosure skill directory that any agent runtime can load. This is the correct spec-compliant layout, generated from a YAML tool spec in under a second.

The prebuilt zero-config path is one command. SQLITE_DATABASE=/path/to.db toolbox-server --prebuilt sqlite --port 5100 skips YAML authoring entirely and ships a ready-to-use execute_sql and list_tables toolset, where list_tables is a 60-line information-schema CTE that returns columns, constraints, indexes, and triggers in detailed mode. The server logs a clear warning that prebuilt configs are intended for build-time (developer-assistant) workflows and not for runtime agents talking to untrusted users, which is the right framing. The same --prebuilt flag accepts 35 source-type values, so the zero-config path covers every supported database.

Engineering discipline matches what you expect from a Google platform team. The tree contains 457 Go test files against roughly 201,821 lines of source, a 1:440 source-to-test ratio. Each MCP protocol version has its own dedicated package (internal/server/mcp/v20241105, v20250326, v20250618, v20251125, vdraft) so adding or sunsetting a spec version is a localized change. There is a dedicated internal/auth/ tree with two providers (generic OIDC and google IAM) plus MCP-level OAuth Protected Resource Metadata generation (--mcp-prm-file, --toolbox-url). SQL injection is mitigated by parameter binding at the driver layer (SQLite uses ?, Postgres uses $1, etc., and the docs are explicit that template parameters using Go text/template are more dangerous and should be used sparingly). The build publishes digital signatures on binaries (added in v1.6.0), the LICENSE is Apache-2.0, and the SECURITY.md routes through Google's standard g.co/vulnz intake.

Four official client SDKs and per-IDE install documentation. The README links to PyPI (toolbox-core), npm (@toolbox-sdk/core), pkg.go.dev (mcp-toolbox-sdk-go), and Maven Central (mcp-toolbox-sdk-java). The docs/en/documentation/connect-to/ides/ directory ships dedicated step-by-step setup guides for Cursor, Windsurf, VS Code (Copilot), Cline, Claude Desktop, Claude Code, Gemini CLI, and Gemini Code Assist, each with copy-pasteable JSON config blocks. The Google Antigravity MCP Store has a click-to-install entry. For most major coding agents, integration is one JSON snippet.

The Bad

The reported server version is the MCP SDK version, not the package version. The MCP initialize handshake returns serverInfo.version: "1.7.0+binary.darwin.arm64.fbe2b21" which is correct, but anyone reading the install docs versus the runtime metadata will see different version surfaces. The PyPI wrapper reports toolbox-server 0.18.0 (the wrapper package) while the embedded Go binary reports 1.7.0. A user who installs the Python wrapper and then logs serverInfo.version for telemetry will see 1.7.0+binary... and may not connect that to PyPI release 0.18.0. The Docker tag is toolbox:1.7.0, the npm wrapper has its own version, and the GitHub release page lists v1.7.0. The actual functionality is correct, but anyone doing version-compatibility checks across install surfaces will need to know which number lives where.

No Hermes-Agent-specific install documentation. The IDE-connect docs cover eight major clients (Cursor, Windsurf, VS Code, Cline, Claude Desktop, Claude Code, Gemini CLI, Gemini Code Assist) and the Gemini extension surface, but Hermes Agent is not on the list. The MCP config pattern is standard (mcpServers with command, args, env) and a Hermes user can copy the Claude Code config block verbatim, but there is no first-party walkthrough. This is a real gap for the GearScope audience specifically, even if it is a small one for the broader market. The skills-generate output also does not write directly to ~/.hermes/skills/ the way Hermes-native skill packs do, so the generated SKILL.md needs a manual move into the right directory.

The 1,071-line README is dense and the navigation is non-obvious. The README is thorough but long: it interleaves the dual-purpose framing, two quick-start paths, install instructions, SDK links, version history, and community pointers. New users land on a wall of badges and prose before reaching the first runnable example. The Hugo-generated docs at mcp-toolbox.dev are better organized, but the README itself is not the fastest onboarding surface. The --prebuilt flag and the skills-generate subcommand are documented, but they are buried below the longer custom-tools walkthrough.

Some prebuilt configs require cloud credentials and the failure mode is hard. The sqlite, postgres, mysql, and mssql prebuilts run locally with just an environment variable. The bigquery, alloydb-postgres, cloud-sql-*, spanner, firestore, looker, cloud-storage, dataplex, and dataproc prebuilts all require Google Cloud Application Default Credentials plus project and region configuration. If you forget the env var, the server refuses to start with error parsing environment variables: environment variable not found: "SQLITE_DATABASE" (or the equivalent for that source). The error is technically correct but unfriendly: it does not say which prebuilt configs are credential-free, nor does it suggest the local-first alternatives. A user trying to evaluate the server without a cloud project will hit this gate fast.

SQLite parameter binding uses ? not :name, and the error when you get it wrong is opaque. The docs say "SQLite uses the ? placeholder for parameters in SQL statements. Parameters are bound in the order they are provided," but the convention in the broader SQL world (and in Postgres and MySQL via this same server) is :name or $1. If you write WHERE city = :city against a SQLite source, the call returns error processing request: unable to execute query: missing named argument "city" rather than a hint that SQLite does not support named placeholders. This is a SQLite driver limitation, not a toolbox bug, but the error message could surface the dialect-specific placeholder rule.

Smoke Test Results

Tested on the host (macOS, aarch64, Python 3.9.6) using pip3 install toolbox-server (PyPI wrapper that bundles the official darwin/arm64 Go binary) and a local SQLite database. No sbx microVM was used. The test corpus was a 2-tool SQLite config (list-hotels unparameterized, find-hotel-by-city with one bound parameter) plus the zero-config --prebuilt sqlite path against a separate users table.

Run A. Fresh install via pip, no credentials

$ pip3 install --quiet toolbox-server
Successfully installed toolbox-server-0.18.0
PASS

$ toolbox-server --version
toolbox version 1.7.0+binary.darwin.arm64.fbe2b21
PASS

$ toolbox-server --help | head -5
Available Commands:
 completion Generate the autocompletion script for the specified shell
 help Help about any command
 invoke Execute a tool directly
 migrate Migrate all configuration files to flat format
 serve Deploy the toolbox server
 skills-generate Generate skills from tool configurations
PASS (5 subcommands, all flags discoverable)

Pass rate: 3 of 3. Clean install with no credentials and no cloud account. The Python wrapper resolves the platform-specific Go binary and exposes it on PATH.

Full install log →

Run B. Server starts and MCP handshake completes (with deps preinstalled)

$ toolbox-server --config tools-new.yaml --address 127.0.0.1 --port 5099
INFO "Initialized 1 sources: test-sqlite"
INFO "Initialized 2 tools: list-hotels, find-hotel-by-city"
INFO "Initialized 2 toolsets: default, hotels-set"
INFO "Initialized 1 promptsets: default"
WARN "wildcard (*) allows any website to access the resources..."
INFO "Server ready to serve!"
PASS (server listening on localhost:5099)

$ curl -X POST http://127.0.0.1:5099/mcp -d '{...initialize...}'
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26",
 "capabilities":{"tools":{"listChanged":false},"prompts":{"listChanged":false}},
 "serverInfo":{"name":"Toolbox","version":"1.7.0+binary.darwin.arm64.fbe2b21"}}}
PASS (announces MCP 2025-03-26, tools + prompts capabilities)

$ curl -X POST .../mcp -d '{...tools/list...}'
{"tools":[{"name":"list-hotels","description":"List all hotels in the database.",
 "inputSchema":{"type":"object","properties":{},"required":[]},
 "annotations":{"readOnlyHint":false,"destructiveHint":true}},
 {"name":"find-hotel-by-city","description":"Find hotels by city.",
 "inputSchema":{"type":"object","properties":{"city":{"type":"string",
 "description":"The city to filter by."}},"required":["city"]},
 "annotations":{"readOnlyHint":false,"destructiveHint":true}}]}
PASS (2 tools, correct JSON Schemas, MCP annotations present, required fields set)

Pass rate: 3 of 3. The server starts cleanly, completes the MCP initialize handshake on protocol version 2025-03-26, and exposes both tools with correct schemas. This is the canonical "does it speak MCP correctly" verdict.

Full server log →

Run C. Tools respond with real output (functional verification)

$ curl -X POST .../mcp -d '{...tools/call list-hotels...}'
{"jsonrpc":"2.0","id":3,"result":{"content":[
 {"type":"text","text":"{\"id\":1,\"name\":\"Hilton SF\",\"city\":\"San Francisco\"}"},
 {"type":"text","text":"{\"id\":2,\"name\":\"Marriott NYC\",\"city\":\"New York\"}"},
 {"type":"text","text":"{\"id\":3,\"name\":\"Hyatt LA\",\"city\":\"Los Angeles\"}"}]}}
PASS (real query, real rows, JSON-per-row MCP content blocks)

$ curl -X POST .../mcp -d '{...tools/call find-hotel-by-city, args:{city:"New York"}...}'
{"jsonrpc":"2.0","id":4,"result":{"content":[
 {"type":"text","text":"{\"id\":2,\"name\":\"Marriott NYC\",\"city\":\"New York\"}"}]}}
PASS (parameterized ? placeholder bound correctly, filtered row returned)

$ toolbox-server invoke --config tools-new.yaml find-hotel-by-city '{"city":"San Francisco"}'
[ {"id":1,"name":"Hilton SF","city":"San Francisco"} ]
PASS (CLI invoke produces the same output without an MCP client)

$ SQLITE_DATABASE=$(pwd)/prebuilt.db toolbox-server --prebuilt sqlite --port 5100
INFO "Using prebuilt tool configurations for: sqlite"
WARN "These prebuilt configs are intended for 'build-time' use cases..."
INFO "Initialized 2 tools: execute_sql, list_tables"
PASS (zero-config prebuilt path works, build-time warning surfaces)

$ curl ... 'tools/call execute_sql {sql:"SELECT * FROM users"}'
{"content":[{"text":"{\"id\":1,\"email\":\"alice@example.com\"}"},
 {"text":"{\"id\":2,\"email\":\"bob@example.com\"}"}]}
PASS (prebuilt execute_sql runs raw SQL)

$ curl ... 'tools/call list_tables {output_format:"simple"}'
{"content":[{"text":"{\"object_details\":{\"name\":\"users\"}}"}]}
PASS (prebuilt list_tables runs 60-line information-schema CTE)

$ echo '{...initialize...}' | toolbox-server --config tools-new.yaml --stdio
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26",
 "capabilities":{"tools":{"listChanged":false},"prompts":{"listChanged":false}},
 "serverInfo":{"name":"Toolbox","version":"1.7.0+binary.darwin.arm64.fbe2b21"}}}
PASS (stdio transport behaves identically to HTTP)

$ toolbox-server skills-generate --config tools-new.yaml --name hotel-lookup \
 --description "Look up hotels" --toolset hotels-set --output-dir ./generated-skills
INFO "Successfully generated skill 'hotel-lookup' with 2 tools."
PASS (3 files emitted: SKILL.md, scripts/list-hotels.js, scripts/find-hotel-by-city.js)

Functional pass rate: 7 of 7. Every tool call returned real data with isError false. The skills-generate output is a valid SKILL.md with proper frontmatter and per-tool Markdown parameter tables. Both MCP transports (HTTP and stdio) and both configuration paths (custom YAML and --prebuilt) work end-to-end.

Full functional log →

What the runs tell you

The server installs, starts, and serves the full MCP surface against a real database without a cloud account or credentials. The two protocol transports behave identically, the prebuilt path is zero-config, and the skills-generate output is a spec-compliant SKILL.md. The only friction is documentation density (the README buries the prebuilt flag below the longer custom-tools walkthrough) and the version-numbering inconsistency between the PyPI wrapper (0.18.0) and the embedded Go binary (1.7.0).

Setup Walkthrough

1. Install the Python wrapper, which bundles the platform-specific Go binary: pip3 install toolbox-server. Verify with toolbox-server --version (should print 1.7.0+binary.darwin.arm64.fbe2b21 or the equivalent for your platform). Alternative install paths are npm install -g @toolbox-sdk/server, the official Docker image us-central1-docker.pkg.dev/database-toolbox/toolbox:1.7.0, or a direct binary download from storage.googleapis.com/mcp-toolbox-for-databases/v1.7.0///toolbox.
2. For the zero-config path, set the env var for your database (for example SQLITE_DATABASE=./app.db) and start the server with toolbox-server --prebuilt sqlite --port 5000. The server exposes execute_sql and list_tables tools immediately. Other prebuilt sources (postgres, mysql, bigquery, alloydb-postgres, cloud-sql-*, spanner, firestore, looker, etc.) follow the same pattern with their own env vars documented under docs/en/documentation/configuration/prebuilt-configs/.
3. For the custom-tools path, write a tools.yaml using the v1.7.0 nested format (each item starts with kind: source, kind: tool, or kind: toolset, separated by ---). Each tool has a type (e.g. sqlite-sql, postgres-sql, mysql-sql, bigquery-execute-sql), a source, a description, a statement, and an optional parameters list. Bind parameters with the dialect-correct placeholder (? for SQLite, $1 for Postgres, ? for MySQL, @param for MS SQL).
4. Start the server: toolbox-server --config tools.yaml --address 127.0.0.1 --port 5000. For local agents, add --stdio instead.
5. To generate an agent SKILL.md from the same config: toolbox-server skills-generate --config tools.yaml --name my-skill --description "..." --toolset my-toolset --output-dir ./skills. The output is a directory containing SKILL.md, scripts/.js for each tool, and assets/tools.yaml. Copy or symlink the directory into your agent's skill location (~/.hermes/skills/ for Hermes, ~/.claude/skills/ for Claude Code, etc.).
6. For an IDE integration, copy the relevant JSON block from docs/en/documentation/connect-to/ides/_mcp.md into your client's MCP config (.mcp.json, claude_desktop_config.json, or equivalent). The block already encodes the binary path, args, and env vars.

Post-install gotchas: the MCP serverInfo.version reports the embedded Go binary version (1.7.0), not the PyPI wrapper version (0.18.0). Cloud-database prebuilts fail fast on missing env vars with error parsing environment variables: environment variable not found: "" rather than a friendly hint. SQLite parameters use ? not :name; using the wrong placeholder returns missing named argument "" rather than a dialect-specific message.

Alternatives

1. awslabs/mcp - the comparable first-party cloud MCP collection from AWS, now in maintenance mode behind the Agent Toolkit for AWS. Use it for the AWS side of a multi-cloud agent. GearScope reviewed it at 4.5/5 KEEP IT.
2. DeusData/codebase-memory-mcp - a codebase-intelligence MCP server (32,669 stars) that focuses on code graphs rather than databases. Use it when the data your agent needs to query is source code rather than rows. GearScope reviewed it at 4.5/5 KEEP IT.
3. Snowflake-Labs/snowflake-mcp or the equivalent first-party vendor MCP for a single database you standardize on. Use these when you want the smallest possible surface and the vendor's blessed integration, at the cost of breadth.