MCP Toolbox for Databases

为什么要用

核心特性

一个二进制，多种引擎：Postgres、MySQL、BigQuery、Spanner、AlloyDB、Cloud SQL、SQLite、MSSQL、Redis、Couchbase、Dgraph、Neo4j
声明式 tools.yaml——每个工具是一条具名的参数化语句，而非开放式 SQL 入口
预置配置（--prebuilt postgres），实现零配置即用
连接池与认证（IAM、OAuth、API key）集中管理，不依赖 prompt
支持 stdio 和 HTTP/SSE 传输——兼容 Claude Desktop、Cursor、Codex、IDE 及自定义 agent
工具级权限规则——可限制哪些角色能调用破坏性语句

实时演示

实际使用效果

mcp-toolbox-databases.replay ▶ 就绪

0/0

安装

选择你的客户端

~/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"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.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 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

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"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "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"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.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 使用服务器对象数组，而非映射。

~/.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"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

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

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： MCP Toolbox for Databases

如何为 Claude 提供对生产 Postgres 的安全只读访问

👤 希望在不引入数据泄露风险的情况下使用 LLM 做数据分析的后端/数据工程师 ⏱ ~25 min intermediate

何时使用： 你希望 Claude 在真实数据库上回答问题，但不想暴露一个可以执行 DROP TABLE 的通用 execute_sql 工具。

前置条件

可通过 libpq URL 访问的 Postgres — 使用只读角色；绝不使用应用的可写用户
已安装 Docker 或 Go — Toolbox 以单一二进制发布；Docker 镜像方式最简单

步骤

使用预置 postgres 配置运行 Toolbox

以 stdio 模式启动 mcp-toolbox，使用 --prebuilt postgres，将 POSTGRES_URL 指向只读副本。✓ 已复制

→ Toolbox 日志显示 tools registered: list_tables, describe_table, execute_sql_readonly
接入 Claude Desktop

将 toolbox 的 docker 配置添加到 claude_desktop_config.json 的 mcpServers 下，然后重启 Claude。✓ 已复制

→ /mcp 列出 toolbox 工具，没有报错
提出真实问题

Toolbox：列出所有表。然后针对 orders 表，过去 7 天的中位订单金额是多少？请展示你运行的 SQL。✓ 已复制

→ Claude 依次调用 list_tables → describe_table → execute_sql_readonly，且 SQL 中只有 SELECT（没有 UPDATE/DELETE）

结果： 在真实数据上进行只读分析，零变更风险，每条查询均有审计日志。

注意事项

连接到了可写用户——Claude 最终会调用到变更工具 — 始终使用只授予 GRANT SELECT 的角色；用 psql 的 \du 确认
并发 agent 调用时连接池耗尽 — 在 tools.yaml 中设置 pool.max_open_conns；默认值较保守

搭配使用： filesystem · github

定义带参数校验的手写分析师工具

👤 不希望暴露原始 SQL、只允许预定义查询的团队 ⏱ ~20 min intermediate

何时使用： 你想让 Claude 回答「本月前 10 名客户」，但不希望它自行构造 JOIN。

前置条件

tools.yaml 文件 — 创建于 ~/.mcp-toolbox/tools.yaml

步骤

编写参数化工具

在 tools.yaml 中添加 top_customers 工具：参数 since: date，语句为 SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ 已复制

→ Toolbox 重新加载，仅暴露 top_customers——没有 execute_sql_readonly
从 Claude 调用

使用 top_customers，since=2026-04-01，并解释结果。✓ 已复制

→ 单次工具调用，带经过校验的日期参数，并返回格式化结果

结果： 锁定的分析接口——Claude 无法运行任何你未声明的内容。

注意事项

忘记移除预置的 execute_sql 工具 — 去掉 --prebuilt；只加载你自己的 tools.yaml

无需手写 SQL 探索 BigQuery 数据集

👤 Google Cloud 上的数据分析师 ⏱ ~20 min intermediate

何时使用： 你有一个 BigQuery 项目，希望 Claude 在有成本保护的情况下跨表回答问题。

前置条件

GCP 项目 + 数据集 — 运行 gcloud auth application-default login，让 Toolbox 自动获取凭证

步骤

使用 --prebuilt bigquery 启动 Toolbox

运行 toolbox --prebuilt bigquery，PROJECT 设为 my-proj。✓ 已复制

→ 工具 bq_list_datasets、bq_dry_run、bq_query 已注册
始终先执行 dry-run

在执行任何查询前，先调用 bq_dry_run 估算扫描字节数。若超过 1GB，请先询问我再执行。✓ 已复制

→ 在计费查询前展示成本估算

结果： 有成本保护的 BigQuery 查询——不会出现意外的高额账单。

注意事项

默认 location 不匹配（US 对 EU） — 设置 BIGQUERY_LOCATION 环境变量

在单次 Claude 会话中查询多个数据库

👤 需要排查跨存储问题的工程师 ⏱ ~30 min advanced

何时使用： 订单数据在 Postgres，事件在 BigQuery，缓存在 Redis——你需要关联全部三个数据源。

前置条件

包含多个数据源的 tools.yaml — 在 sources: 下定义每个数据源，并为工具标记对应的数据源

步骤

接入三个数据源

在 tools.yaml 中将 postgres-prod、bq-events、redis-cache 添加为数据源，每个数据源各添加 1–2 个工具。✓ 已复制

→ Toolbox 启动，所有数据源标记为健康
提出跨存储问题

针对订单 12345：从 Postgres 拉取该行记录，从 BigQuery 获取事件时间线，从 Redis 获取当前缓存状态，然后进行综合分析。✓ 已复制

→ 三次工具调用并发执行，返回单一连贯的答案

结果： 跨存储调试，无需三个独立工具或 SSH 会话。

注意事项

数据源健康检查静默失败 — 启动前运行 toolbox validate tools.yaml

搭配使用： filesystem

组合

与其他 MCP 搭配，撬动十倍杠杆

mcp-toolbox-databases + filesystem

拉取查询结果并写入工作区的 CSV 文件

Toolbox：本周前 100 条订单。Filesystem：保存为 /tmp/orders.csv。✓ 已复制

mcp-toolbox-databases + github

Claude 提出 schema 变更方案后，提交包含 SQL migration 的 PR

Toolbox：描述 orders 表。GitHub：提 PR，在 customer_id 上添加索引。✓ 已复制

工具

此 MCP 暴露的能力

工具	输入参数	何时调用	成本
list_tables	schema?: str	探索的第一步	1 query
describe_table	table: str	在对未知表写 SQL 之前调用	1 query
execute_sql_readonly	sql: str	在只读副本上执行自由分析	1 query
bq_dry_run	sql: str	BigQuery：始终在 bq_query 之前调用	free (dry run)
bq_query	sql: str	dry run 确认成本可接受后调用	按扫描字节数计费
<your-custom-tool>	取决于 tools.yaml	你在 tools.yaml 中声明的任何工具	1 query

成本与限制

运行它的成本

API 配额: 无限制——受限于你的数据库连接上限
每次调用 Token 数: 100–5000，取决于结果大小
费用: 开源免费；底层数据库/云服务按正常收费
提示: 在 tools.yaml 中限制返回行数（如 LIMIT 200）；BigQuery 始终先过 bq_dry_run

安全

权限、密钥、影响范围

最小权限： 只读数据库角色

凭据存储： 环境变量或 Google ADC；Toolbox 不持久化凭证

数据出站： 直接数据库连接——无第三方中转。Toolbox 仅限本地。

切勿授予： DBA 生产库上的 DROP/TRUNCATE

生产库始终应通过只读副本 + 只读角色访问；绝不使用应用的可写用户

故障排查

常见错误与修复

connection refused / 连接池耗尽

在 tools.yaml 中增大 pool.max_open_conns；检查数据库连接上限

验证： psql，执行 SELECT count(*) FROM pg_stat_activity

tool not found

使用 --prebuilt 时，工具名如 pg_list_tables；运行 toolbox list-tools 确认

BigQuery 403 access denied

运行 gcloud auth application-default login，并授予 roles/bigquery.dataViewer

验证： bq ls

Spanner Cloud SDK 报错

将 GOOGLE_APPLICATION_CREDENTIALS 设置为服务账号 JSON 文件路径

替代方案