db-mcp-server

一个本地 MCP 服务器，为 AI 编码助手（例如 Claude Code）提供对 PostgreSQL 数据库的凭据隔离访问。助手只发送 SQL，只接收行数据——数据库用户名、密码和 SSH 密钥永远不会进入模型的上下文或对话记录中。

为什么

将 AI 助手连接到数据库通常意味着要把连接字符串和密码放在模型（及其对话记录）可以读取的地方。这个服务器保持了这一边界：它拥有加密凭据和 SSH 隧道，只暴露一个小的仅 SQL 工具面，并且默认只读。

Related MCP server: Postgres Scout MCP

工作原理

• 目录（registry.yaml）——非机密路由。组织为 customers → environments → services；每个服务映射到一个数据库名称和一个 secret_ref（指向保险库的指针——绝不是凭据）。

• 保险库（vault.enc）——AES-256-GCM，使用 scrypt 派生的密钥。保存数据库凭据，启动时使用口令解密到内存中一次。

• 隧道池——通过 sshtunnel 为每个 (customer, environment) 建立一个 SSH 隧道，绑定到临时的 127.0.0.1 端口。

• 执行器——psycopg。run_query 在 Postgres READ ONLY 事务中运行（引擎拒绝任何写入）；run_write_query 需要 confirm=true。

安装

python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1   (bash: source .venv/Scripts/activate)
pip install -e ".[dev]"

配置

配置来自环境变量；默认值相对于项目根目录解析。

配置（首次设置）

1. 复制模板并填写真实值：

   cp bootstrap.example.yaml bootstrap.yaml

2. 将你的 SSH 私钥放入 keys/（文件名必须与目录中的 pem_key 字段匹配）。

3. 生成非机密目录和加密保险库（提示输入你之后运行服务器时复用的口令）：

   python -m db_mcp_server.bootstrap --dry-run   # preview, writes nothing
   python -m db_mcp_server.bootstrap             # writes registry.yaml + vault.enc
   python -m db_mcp_server.vault_admin verify     # expect {"ok": true}

bootstrap.yaml 包含明文凭据——它被 git 忽略；一旦保险库存在，删除它或将其离线保存。

命令行工具

（控制台命令在 pip install -e . 后可用；python -m db_mcp_server.<module> 形式始终有效。）

暴露给助手的工具

• list_databases() — 目录（customers → environments → services）；无机密。

• run_query(customer, environment, service, sql, max_rows?) — 只读。

• run_write_query(customer, environment, service, sql, confirm) — 受控写入。

域错误以结构化的 {error_code, message} 返回，而不是异常，因此助手可以做出反应。

注册到 MCP 客户端

示例 .mcp.json（调整路径）。使用 ${DB_MCP_PASSPHRASE} 以便从 shell 读取口令，而不是写入文件：

{
  "mcpServers": {
    "db": {
      "command": "/absolute/path/to/db-mcp-server/.venv/Scripts/python.exe",
      "args": ["-m", "db_mcp_server.server"],
      "env": {
        "DB_MCP_PASSPHRASE": "${DB_MCP_PASSPHRASE}"
      }
    }
  }
}

安全说明

• vault.enc、keys/、bootstrap.yaml、*.env 和 *.pem 被 git 忽略——切勿提交。

• 保险库口令通过 DB_MCP_PASSPHRASE（或提示）提供——绝不存储在 registry.yaml、argv 或日志中。

• db-vault 通过隐藏提示（getpass）读取数据库密码，绝不通过 argv。

• run_query 在 Postgres 引擎级别是只读的；写入需要 confirm=true。

测试

pip install -e ".[dev]" && python -m pytest -q

除非 DB_MCP_TEST_DSN 指向可访问的 PostgreSQL，否则数据库集成测试会被跳过。

路线图（不在当前构建中）

持久化审计跟踪、多用户操作、外部密钥管理器支持、模式内省工具，以及将凭据隔离变成硬边界的权限拒绝列表。