dbridge-mcp

dbridge-mcp

一个 MCP 服务，让 AI Agent 能以自然语言查询 SQL 数据库，并确保安全且只读。

Agent 会自行发现架构（list_tables、describe_table），然后根据用户提出的问题编写并运行 SELECT。无需为每个问题手写端点。

支持 SQLite、PostgreSQL 和 MySQL / MariaDB。

为什么选择 dbridge

原始 LLM 无法知道数据库中有什么内容，而网络搜索也无法访问私有数据。dbridge 为模型提供了一道受保护的数据入口：它可以读取并回答问题，但无法写入、删除表，也无法泄露整张表的数据。

为什么选择 dbridge，而不是其他数据库 MCP？

数据库 MCP 服务有很多。dbridge 围绕一个理念构建——你应该能够放心地让 AI 连接真实数据库——这也体现在单引擎服务不具备的组合功能上：

• 一个服务，三种引擎。 SQLite、PostgreSQL 和 MySQL/MariaDB 使用相同的工具和配置。只需更改连接字符串即可切换数据库，无需更换工具。
• 双重只读保护。 SQL 防护机制会拒绝 SELECT/WITH 以外的语句，且每个查询都会在数据库强制执行的 READ ONLY 事务中运行——因此，即使查询绕过了防护机制，也无法写入数据。
• 列级隐私保护。 可以完全向模型隐藏某些列，也可以屏蔽值（a***@site.com），同时保留查询能力。大多数服务都会暴露连接所能访问的所有内容。
• 控制潜在影响范围。 强制限制行数上限，确保其优先于用户提供的 LIMIT；设置每次查询的超时时间；使用 EXPLAIN 拒绝成本过高的查询；限制每分钟的请求次数；并限制连接池容量。
• 无需原生构建步骤。 SQLite 使用 Node 内置的 node:sqlite，因此运行 npx -y dbridge-mcp 无需编译器工具链。
• 洞察性能，而不只是执行查询。 column_stats 和 index_health 可向模型提供真实的基数和索引使用数据；test_index 则会使用 hypopg 模拟索引，让模型在任何人创建索引之前评估效果——因此，模型的优化建议基于实际数据库，而非猜测。

如果你只需要“让 Agent 运行 SQL”，有很多服务都能做到。dbridge 适用于需要让 Agent 访问重要数据的场景。

工具

工具	用途
list_tables	列出数据库中的所有表。
describe_table	返回表的列、主键、外键和行数估算值。
sample_table	预览表的前几行（json/csv/markdown）。
count_rows	返回表的精确行数。
run_query	执行一条只读 SELECT / WITH 查询，并以 json、csv 或 markdown 格式返回行。
explain_query	返回查询计划和预估成本，但不执行查询。
column_stats	按列统计不同值的数量和空值占比——此列的选择性是否足以建立索引？
index_health	列出索引及其大小和扫描次数，并标记未使用、重复和无效的索引。
test_index	模拟执行 CREATE INDEX，但不实际建立索引，并报告查询规划器是否会使用该索引（PostgreSQL，通过 hypopg）。
slow_queries	记录中开销最高的语句及其调用次数和执行时间（PostgreSQL pg_stat_statements、MySQL performance_schema）。
get_limits	报告当前生效的安全限制（上限、超时、隐藏/屏蔽的列）。

资源

资源	用途
dbridge://schema	将完整架构（所有表及其列）作为一个 JSON 文档提供。

提示词

提示词	用途
optimize	引导式优化流程：查找慢查询、检查查询计划和索引健康状况，并在提出索引建议前使用 test_index 验证每项建议。

要求

Node.js 22.5+（SQLite 使用内置的 node:sqlite，无需原生构建步骤）。

安装

发布的包附带 dbridge-mcp 二进制文件，因此无需克隆或构建即可使用。使用连接参数指定数据库：

npx -y dbridge-mcp demo.db                                  # SQLite (file path)
npx -y dbridge-mcp "postgresql://user:pass@host:5432/mydb"  # PostgreSQL
npx -y dbridge-mcp "mysql://user:pass@host:3306/mydb"       # MySQL / MariaDB

数据库引擎根据连接字符串选择：文件路径表示 SQLite，postgres:// / postgresql:// 表示 PostgreSQL，mysql:// 表示 MySQL/MariaDB。

或者全局安装一次：

npm install -g dbridge-mcp
dbridge-mcp "postgresql://user:pass@host:5432/mydb"

MCP 客户端会将服务作为子进程启动——请参阅下方的客户端章节。

Windows 注意事项： MCP 客户端无法在 Windows 上直接启动 npx，因为它是 .cmd 脚本。请使用 cmd /c 包装——设置 "command": "cmd"，并在 args 中加入 "/c", "npx", "-y", "dbridge-mcp", "<connection>"。以下示例使用直接形式（macOS/Linux）；在 Windows 上请添加 cmd /c 前缀。

在 Claude Desktop 中使用

Claude Desktop 仅支持单个全局配置。将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "dbridge": {
      "command": "npx",
      "args": ["-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "env": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }
    }
  }
}

对于本地 SQLite 文件，请将连接字符串替换为 .db 文件的绝对路径。重启 Claude Desktop，然后提问："上个月销量最高的 5 种产品是什么？"

在 Claude Code 中使用

使用 CLI 将其添加到当前项目：

claude mcp add dbridge --scope project \
  -e DBRIDGE_CONFIG=/absolute/path/to/dbridge.config.json \
  -- npx -y dbridge-mcp "postgresql://user:pass@host:5432/mydb"

--scope project 会在项目根目录中写入可共享的 .mcp.json；使用 --scope user 可添加全局服务，省略该参数则添加仅供当前项目使用的私有服务。.mcp.json 内容如下：

{
  "mcpServers": {
    "dbridge": {
      "command": "npx",
      "args": ["-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "env": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }
    }
  }
}

在该目录中运行 claude；批准一次项目服务，然后使用 /mcp 检查它。

在 Cursor 中使用

将相同的 mcpServers 块添加到项目根目录中的 .cursor/mcp.json（或添加到 ~/.cursor/mcp.json 以供所有项目使用），然后在 设置 → MCP 下启用该服务，再向 Agent 提出有关数据的问题。

在 Windsurf 中使用

将相同的 mcpServers 块添加到 ~/.codeium/windsurf/mcp_config.json，然后在 设置 → Cascade → MCP 下刷新服务列表。

在 OpenCode 中使用

添加到 opencode.json（项目根目录或 ~/.config/opencode/opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dbridge": {
      "type": "local",
      "command": ["npx", "-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "enabled": true
    }
  }
}

若要调整安全保护机制，请通过 environment 块指定服务使用的配置文件：

"environment": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }

Docker

构建镜像并通过 stdio 运行服务：

docker build -t dbridge-mcp .
docker run --rm -i dbridge-mcp "postgresql://user:pass@host:5432/mydb"

挂载配置文件，并将 DBRIDGE_CONFIG 指向该文件：

docker run --rm -i \
  -v "$PWD/dbridge.config.json:/config.json:ro" \
  -e DBRIDGE_CONFIG=/config.json \
  dbridge-mcp "postgresql://user:pass@host:5432/mydb"

安全性

• 连接以只读方式打开。在 PostgreSQL 和 MySQL 中，每个查询也都会在 READ ONLY 事务内运行，因此即使查询绕过了防护，数据库本身也会拒绝写入。
• 只有 SELECT 和 WITH 语句可以通过；写入、DDL 和修改数据的 CTE 都会被拒绝。
• 每次调用只能执行一条语句；即使查询指定了更大的 LIMIT，也会强制执行行数上限（默认 1000 行）。
• 每个 PostgreSQL 和 MySQL 查询都有单独的超时时限（statement_timeout / max_execution_time），因此失控或开销过大的查询不会长时间占用数据库。
• 系统目录和凭据表（information_schema、pg_authid、sqlite_master 等）不可查询；架构发现需通过工具进行。
• 可以完全隐藏受限列：模型无法在架构中看到这些列、查询这些列，也不会在结果中收到这些列。
• 可以使用允许列表或阻止列表限制表；被阻止的表不可见，也不可查询。
• 可以对列进行脱敏，而不是隐藏：列仍然可见，但返回的值会被部分隐藏（例如 a***@site.com）。
• 可以通过 EXPLAIN 成本估算提前拒绝开销过大的查询，也可以按分钟对调用方进行速率限制。
• 连接池大小设有上限，因此 dbridge 无法耗尽数据库的连接。

配置

每项设置都有三个来源，优先级依次递增：JSON 文件（DBRIDGE_CONFIG）、环境变量，然后是 CLI 标志。因此，你可以完全不使用 JSON 文件，只设置所需的选项：

npx -y dbridge-mcp "postgresql://user:pass@host/db" --max-rows 200 --statement-timeout-ms 3000 --masked-columns email,iban
DBRIDGE_MAX_ROWS=200 DBRIDGE_REQUIRE_SSL=true npx -y dbridge-mcp "postgresql://user:pass@host/db"

也可以将所有设置放在同一处：将 DBRIDGE_CONFIG 指向一个 JSON 文件（完整模板请参见 dbridge.config.example.json）。所有字段均为可选项：

{
  "maxRows": 500,
  "hiddenColumns": ["ssn", "password_hash"],
  "maskedColumns": ["iban", { "column": "email", "strategy": "email" }],
  "allowedTables": ["products", "sales", "customers"],
  "blockedTables": ["employees", "audit_log"],
  "statementTimeoutMs": 5000,
  "maxCost": 100000,
  "rateLimitPerMin": 60,
  "maxPoolSize": 5,
  "connectionTimeoutMs": 10000,
  "requireSsl": true,
  "schemas": ["public", "reporting"],
  "auditLog": true
}

字段	CLI 标志 / 环境变量	默认值	用途
maxRows	--max-rows / DBRIDGE_MAX_ROWS	1000	每次查询返回的行数上限，即使 LIMIT 更大也会强制执行。
hiddenColumns	--hidden-columns / DBRIDGE_HIDDEN_COLUMNS	[]	从架构、查询和结果中隐藏的列。
maskedColumns	--masked-columns / DBRIDGE_MASKED_COLUMNS	[]	结果中值会被脱敏的列（见下文）。
maxCellChars	--max-cell-chars / DBRIDGE_MAX_CELL_CHARS	0	将超过此长度的字符串单元格截断；0 表示禁用。
maxResultBytes	--max-result-bytes / DBRIDGE_MAX_RESULT_BYTES	0	限制序列化结果的总大小，并丢弃末尾的行；0 表示禁用。
allowedTables	--allowed-tables / DBRIDGE_ALLOWED_TABLES	[]	如果非空，则仅公开这些表。
blockedTables	--blocked-tables / DBRIDGE_BLOCKED_TABLES	[]	始终隐藏且不可查询的表。
statementTimeoutMs	--statement-timeout-ms / DBRIDGE_STATEMENT_TIMEOUT_MS	10000	每次查询的超时时间（PostgreSQL statement_timeout、MySQL max_execution_time）；0 表示禁用。
maxCost	--max-cost / DBRIDGE_MAX_COST	0	拒绝 EXPLAIN 成本估算超过此值的查询（PostgreSQL/MySQL）；0 表示禁用。
rateLimitPerMin	--rate-limit-per-min / DBRIDGE_RATE_LIMIT_PER_MIN	0	每分钟执行查询的工具调用次数上限；0 表示禁用。
maxPoolSize	--max-pool-size / DBRIDGE_MAX_POOL_SIZE	5	连接池中的最大连接数（PostgreSQL/MySQL）。
connectionTimeoutMs	--connection-timeout-ms / DBRIDGE_CONNECTION_TIMEOUT_MS	10000	等待连接的最长时间（PostgreSQL/MySQL）。
requireSsl	--require-ssl / DBRIDGE_REQUIRE_SSL	false	要求使用经过验证的 TLS 连接（PostgreSQL/MySQL）。
schemas	--schemas / DBRIDGE_SCHEMAS	["public"]	仅适用于 PostgreSQL：要公开的架构；多个架构会生成 schema.table 名称。
auditLog	--audit-log / DBRIDGE_AUDIT_LOG	false	将每次工具调用（查询、行数、耗时、错误）以 JSON 格式记录到 stderr。

命令行或环境变量中的列表值以逗号分隔（--allowed-tables products,sales）。

引擎说明：statementTimeoutMs、maxCost、maxPoolSize、connectionTimeoutMs、requireSsl 和 schemas 适用于联网引擎（PostgreSQL/MySQL）。SQLite 使用本地文件，因此会忽略这些选项；行数上限、列/表访问控制和脱敏适用于所有引擎。

列脱敏

maskedColumns 会保留列的可见性，但对其值进行脱敏。每个条目可以是列名（默认使用 partial 策略），也可以是对象 { "column": ..., "strategy": ..., "keep": ... }：

策略	示例输入	输出
partial（默认）	TR120000123456	**********3456（保留最后 keep 位，默认为 4 位）
email	[email protected]	a***@site.com
full	任意值	***

与 hiddenColumns 不同，脱敏列仍可用于 WHERE/GROUP BY，因此，对于真正的机密信息请使用 hiddenColumns，对于应可识别但不应公开的值，请使用 maskedColumns。

输出格式

run_query 和 sample_table 可接受可选的 format 参数：json（默认，完整结果对象）、csv 或 markdown。CSV 和 Markdown 会返回以简短的 rows: N · Nms 标题开头的精简表格，便于减少令牌用量并提高可读性。结合使用 maxCellChars 和 maxResultBytes，可控制大型结果的大小。

连接生产数据库

• 通过 DBRIDGE_DB_PATH 环境变量传递连接字符串，而不是通过命令行传递，这样密码就不会出现在进程列表中。
• 优先使用专用数据库角色，并仅授予其对你要公开的表的只读权限——这才是真正的安全边界；防护机制则是纵深防御。
• 设置保守的 statementTimeoutMs、maxRows 和 maxCost，并使用 allowedTables 仅公开报表表。

本地开发

要参与 dbridge 本身的开发，请克隆仓库并从源代码构建：

npm install
npm run build
npm run seed        # creates demo.db (a small store: products, customers, sales)
node dist/index.js demo.db

使用 MCP Inspector 试用

npm run inspect

然后在 Inspector UI 中调用工具。无需大模型或 API 密钥。

测试

npm test

更新日志

请参阅 CHANGELOG.md。

许可证

MIT