MCP Toolbox for Databases — Install & Live Demo

Why use it

Key features

One binary, many engines: Postgres, MySQL, BigQuery, Spanner, AlloyDB, Cloud SQL, SQLite, MSSQL, Redis, Couchbase, Dgraph, Neo4j
Declarative tools.yaml — each tool is a named, parameterized statement, not a free-form SQL hatch
Prebuilt configs (--prebuilt postgres) for instant zero-config use
Connection pooling and auth (IAM, OAuth, API key) handled centrally, not in your prompt
Stdio or HTTP/SSE transport — works with Claude Desktop, Cursor, Codex, IDEs, custom agents
Per-tool authorization rules — restrict who can call destructive statements

Live Demo

What it looks like in practice

mcp-toolbox-databases.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use MCP Toolbox for Databases

How to give Claude safe read-only access to a production Postgres

👤 Backend / data engineers wanting LLM analytics without an exfil risk ⏱ ~25 min intermediate

When to use: You want Claude to answer questions over a real database without a generic execute_sql tool that can DROP TABLE.

Prerequisites

Postgres reachable via libpq URL — Use a read-only role; never the app's writable user
Docker or Go installed — Toolbox ships as a single binary; Docker image is easiest

Flow

Run Toolbox with the prebuilt postgres profile

Start mcp-toolbox in stdio mode using --prebuilt postgres and POSTGRES_URL pointing at the read replica.✓ Copied

→ Toolbox logs tools registered: list_tables, describe_table, execute_sql_readonly
Wire it into Claude Desktop

Add the toolbox docker config to claude_desktop_config.json under mcpServers, then restart Claude.✓ Copied

→ /mcp lists toolbox tools — no failures
Ask a real question

Toolbox: list tables. Then for orders, what's the median order value in the last 7 days? Show me the exact SQL you ran.✓ Copied

→ Claude calls list_tables → describe_table → execute_sql_readonly with a SELECT (never UPDATE/DELETE)

Outcome: Read-only analytics over real data with zero risk of mutation, audit log of every query.

Pitfalls

Pointed at the writable user — Claude eventually calls a mutating tool — Always use a role with GRANT SELECT only; verify with \du in psql
Connection pool exhausted under parallel agent calls — Set pool.max_open_conns in tools.yaml; default is conservative

Combine with: filesystem · github

Define a hand-written analyst tool with parameter validation

👤 Teams who don't want raw SQL, only sanctioned queries ⏱ ~20 min intermediate

When to use: You want Claude to answer 'top 10 customers this month' but never invent its own joins.

Prerequisites

tools.yaml file — Create at ~/.mcp-toolbox/tools.yaml

Flow

Write a parameterized tool

Add a tool top_customers to tools.yaml: parameter since: date, statement SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ Copied

→ Toolbox reloads, exposes top_customers only — no execute_sql_readonly
Call from Claude

Use top_customers since=2026-04-01 and explain the result.✓ Copied

→ Single tool call with validated date param, formatted result

Outcome: Locked-down analyst surface — Claude cannot run anything you didn't declare.

Pitfalls

Forgetting to remove the prebuilt execute_sql tool — Drop --prebuilt; load only your tools.yaml

Explore BigQuery datasets without writing SQL

👤 Analysts on Google Cloud ⏱ ~20 min intermediate

When to use: You have a BigQuery project and want Claude to answer questions across it with cost guardrails.

Prerequisites

GCP project + dataset — Run gcloud auth application-default login so Toolbox picks up creds

Flow

Start Toolbox with --prebuilt bigquery

Run toolbox --prebuilt bigquery with PROJECT=my-proj.✓ Copied

→ Tools bq_list_datasets, bq_dry_run, bq_query registered
Always dry-run first

Before running any query, call bq_dry_run to estimate the bytes scanned. If > 1GB, ask me before running.✓ Copied

→ Cost estimate shown before billable query

Outcome: BigQuery answers with cost guardrails — no surprise $200 query.

Pitfalls

Default location mismatch (US vs EU) — Set BIGQUERY_LOCATION env var

Query multiple databases from one Claude session

👤 Engineers debugging cross-store issues ⏱ ~30 min advanced

When to use: Order data is in Postgres, events in BigQuery, cache in Redis — you need correlation across all three.

Prerequisites

tools.yaml with multiple sources — Define each source under sources: and tag tools with the source

Flow

Wire all three sources

Add postgres-prod, bq-events, redis-cache as sources in tools.yaml. Add 1–2 tools per source.✓ Copied

→ Toolbox starts, all sources marked healthy
Ask a cross-store question

For order 12345: pull the row from Postgres, the event timeline from BigQuery, and the current cache state from Redis. Reconcile.✓ Copied

→ Three tool calls fanned out, single coherent answer

Outcome: Cross-store debugging without three separate tools or SSH sessions.

Pitfalls

Source health check fails silently — Run toolbox validate tools.yaml before starting

Combine with: filesystem

Combinations

Pair with other MCPs for X10 leverage

mcp-toolbox-databases + filesystem

Pull a query result and write it to a CSV in your workspace

Toolbox: top 100 orders this week. Filesystem: save as /tmp/orders.csv.✓ Copied

mcp-toolbox-databases + github

Open a PR with a SQL migration after Claude proposes a schema change

Toolbox: describe the orders table. GitHub: open a PR adding an index on customer_id.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_tables	schema?: str	First exploration step	1 query
describe_table	table: str	Before writing SQL against an unknown table	1 query
execute_sql_readonly	sql: str	Free-form analytics over the read replica	1 query
bq_dry_run	sql: str	BigQuery: always before bq_query	free (dry run)
bq_query	sql: str	After dry run shows acceptable cost	billable per bytes scanned
<your-custom-tool>	depends on tools.yaml	Anything you've declared in tools.yaml	1 query

Cost & Limits

What this costs to run

API quota: None — limited by your DB's connection cap
Tokens per call: 100–5000 depending on result size
Monetary: Free OSS; underlying DB / cloud billed normally
Tip: Cap result rows in tools.yaml (e.g. LIMIT 200); for BigQuery always go through bq_dry_run first

Security

Permissions, secrets, blast radius

Minimum scopes: read-only DB role

Credential storage: Env vars or Google ADC; Toolbox never persists creds

Data egress: Direct DB connection — no third-party hop. Toolbox is local only.

Never grant: DBA DROP/TRUNCATE on prod

Always front prod with a read replica + read-only role; never the app's writable user

Troubleshooting

Common errors and fixes

connection refused / pool exhausted

Increase pool.max_open_conns in tools.yaml; check DB conn limit

Verify: psql, run SELECT count(*) FROM pg_stat_activity

tool not found

If using --prebuilt, the tool name is e.g. pg_list_tables; check toolbox list-tools

BigQuery 403 access denied

Run gcloud auth application-default login and grant roles/bigquery.dataViewer

Verify: bq ls

Spanner Cloud SDK errors

Set GOOGLE_APPLICATION_CREDENTIALS to a service account JSON

Alternatives

MCP Toolbox for Databases vs others

Alternative	When to use it instead	Tradeoff
DBHub	You want a single zero-dep binary covering Postgres/MySQL/SQL Server	Less BigQuery/Spanner depth, no Google IAM
Postgres MCP (modelcontextprotocol)	Postgres-only, no YAML config	Less restrictive — exposes execute_sql by default
MySQL MCP (benborla)	MySQL-only, read-only	Single-engine, simpler

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills