MCP Toolbox for Databases in Claude Code your database, one claude mcp add away.
Google's MCP Toolbox for Databases connects an agent to Postgres, MySQL, BigQuery, and more through a declarative tools file. Here's how to register it with Claude Code — CLI or .mcp.json — and debug it when it won't connect.
MCP Toolbox for Databases (github.com/googleapis/genai-toolbox, 15.5k stars) is Google's open-source MCP server for database access. Instead of handing the agent a raw SQL pipe, you declare sources and tools in a tools.yaml file — each tool is a named, parameterized query — and the Toolbox exposes exactly those operations and nothing else.
For Claude Code that's a strong pairing: the agent can inspect schemas, run the queries you've sanctioned, and use the results mid-task, while your terminal session never holds an open psql connection the model can free-style against. It ships as an OCI container image, so Docker (or Podman) is the only prerequisite.
Write a minimal tools.yaml
The Toolbox is configuration-driven. A tools.yaml names your database sources (it supports engines including PostgreSQL, MySQL, SQL Server, BigQuery, and Spanner — see the repo docs for the full matrix) and the tools agents may call against them. Start with one source and one or two read-only tools; you can grow the file as trust grows.
Register the server with Claude Code
Claude Code takes MCP servers two ways: the claude mcp add CLI for your user scope, or a .mcp.json checked into the project root so the whole team gets the server. The CLI one-liner is: claude mcp add toolbox -- docker run -i --rm -v /abs/path/tools.yaml:/config/tools.yaml us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --tools-file /config/tools.yaml --stdio. For the project-scoped version, commit this file:
{
"mcpServers": {
"toolbox": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/abs/path/tools.yaml:/config/tools.yaml",
"us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
"--tools-file", "/config/tools.yaml",
"--stdio"
]
}
}
}Check the connection
Run claude mcp list to see the server's status, or type /mcp inside a session for a live view of connected servers and their tools. Each tool you declared in tools.yaml should appear by name. Then ask Claude Code something only the database can answer and confirm it reaches for a Toolbox tool instead of guessing.
Troubleshooting in Claude Code
The flag that bites everyone: docker run needs -i. Claude Code talks to the server over stdin/stdout, and without -i Docker closes stdin and the handshake dies instantly. The volume mount is the second trap — the host side of -v must be an absolute path, and the --tools-file flag must point at the container side of that mount.
If the server shows as failed in claude mcp list, run the docker command by hand in a terminal; the Toolbox prints YAML validation errors and database connection failures to stderr, which is far easier to read there. Remember the container has its own network namespace: a Postgres on your host is host.docker.internal, not localhost, from inside it. Config changes need a new session or a /mcp reconnect — a running session won't re-read .mcp.json.
The live listing
MCP Toolbox for Databases has a live listing on the Loomal marketplace at https://loomal.ai/marketplace/mcp-toolbox-for-databases with its probed tool surface. If you publish your own MCP server, claiming its listing on Loomal verifies ownership and lets you attach per-call pricing for agent traffic.
FAQ
How do I install the Toolbox for Databases in Claude Code?
Either run claude mcp add toolbox -- docker run -i --rm -v <abs-path>/tools.yaml:/config/tools.yaml <image> --tools-file /config/tools.yaml --stdio, or commit the equivalent entry to a .mcp.json in your project root. Verify with claude mcp list or the /mcp command in a session.
Where does Claude Code store MCP configuration?
Servers added via the claude mcp add CLI live in your user configuration; project-scoped servers live in a .mcp.json file at the repo root, which is the right place for a shared database toolbox since teammates get it on checkout.
Why does the server connect and immediately drop?
Almost always a missing -i on docker run — stdio transport requires an open stdin. If -i is present, run the same command manually: a tools.yaml validation error or an unreachable database makes the Toolbox exit at startup, and its stderr says exactly why.
Does the agent get arbitrary SQL access?
No — that's the point of the Toolbox design. The agent can only invoke the named tools you define in tools.yaml, each bound to a specific parameterized statement. Adding a new capability means deliberately adding a new tool to the file.
Browse more MCP servers for Claude Code.
Live-probed tool lists on every Loomal listing.