用途
dbridge-mcp 是一个 MCP 服务器，允许 AI 智能体用自然语言查询 SQL 数据库，且安全、只读。原始 LLM 无法知道数据库里的内容，网络搜索也无法访问私有数据；dbridge 为模型提供一扇有防护的门：模型可以读取并回答问题，但不能写入、删除或泄露整张表。智能体会自行发现 schema（通过 list_tables、describe_table），然后针对用户提问编写并运行 SELECT，不需要为每个问题手写端点。
支持的引擎
同一服务器支持三种引擎：SQLite、PostgreSQL、MySQL/MariaDB，使用相同的工具和配置。引擎由连接字符串决定：文件路径为 SQLite，postgres:// 或 postgresql:// 为 PostgreSQL，mysql:// 为 MySQL/MariaDB。切换数据库只需更改连接字符串，无需更换工具。
主要能力
- 只读双重保障：SQL 守卫拒绝除 SELECT/WITH 之外的语句，且每次查询都在数据库强制的 READ ONLY 事务中运行，即使查询绕过守卫也无法写入。
- 列级隐私：可完全隐藏列（模型在 schema 中看不到、无法查询、结果中也没有），或对值进行掩码（如 a***@site.com）但仍可查询。
- 影响范围控制：强制执行行数上限（即使查询自带更大的 LIMIT，默认上限 1000 行）、每查询超时、基于 EXPLAIN 的成本拒绝昂贵查询、每分钟速率限制以及受限连接池。
- 无原生构建步骤：SQLite 使用 Node 内置的 node:sqlite，npx -y dbridge-mcp 无需编译器工具链。
- 性能洞察：column_stats 和 index_health 提供真实基数与索引使用数据，test_index 可用 hypopg 模拟索引后再决定是否创建，让模型的优化建议基于实际数据库而非猜测。
使用方式
需要 Node.js 22.5+。已发布的包自带 dbridge-mcp 二进制，无需克隆或构建。通过连接参数指向数据库：npx -y dbridge-mcp <connection>。也可全局安装一次。
MCP 客户端会作为子进程启动服务器。Claude Desktop 需在 claude_desktop_config.json 中添加配置；Claude Code 可用 CLI 添加（--scope project 写入 .mcp.json，--scope user 为全局）；Cursor 需在 .cursor/mcp.json 添加 mcpServers 块；Windsurf 在 ~/.codeium/windsurf/mcp_config.json 添加；OpenCode 在 opencode.json 添加。Windows 上由于 npx 是 .cmd 脚本，需用 cmd /c 包装，使用 "command": "cmd" 并在 args 中放置 "/c", "npx", "-y", "dbridge-mcp", "<connection>"。
还可通过环境变量 DBRIDGE_CONFIG 指向 JSON 配置文件来调整安全守卫。所有设置有三种来源，优先级从低到高：JSON 文件、环境变量、CLI 标志。命令行或环境变量中的列表值用逗号分隔（如 --allowed-tables products,sales）。
适用场景
- 将 AI 智能体指向真实且需要保护的数据，例如让智能体回答“上个月最畅销的 5 个产品是什么？”。
- 在生产数据库上运行：建议通过 DBRIDGE_DB_PATH 环境变量传递连接字符串，避免密码出现在进程列表；使用仅对目标表有只读授权的专用数据库角色；设置保守的 statementTimeoutMs、maxRows、maxCost，并用 allowedTables 仅暴露报表表。
- 本地开发与调测：可克隆仓库从源码构建，并配合 MCP Inspector 测试工具，无需 LLM 或 API 密钥。
限制
- 每个调用只允许一条语句，行数上限始终生效。
- 系统目录和凭据表（information_schema、pg_authid、sqlite_master 等）不可查询，schema 发现需通过工具进行。
- tables 可通过允许列表或阻止列表限制，被阻止的表不可见且无法查询。
- 被掩码的列仍可用于 WHERE/GROUP BY；真正的秘密应使用 hiddenColumns，需要可识别但不暴露的值使用 maskedColumns。
- run_query 和 sample_table 支持可选 format 参数：json（默认完整结果对象）、csv 或 markdown，后两者返回带简短 rows: N · Nms 表头的紧凑表格，可结合 maxCellChars 和 maxResultBytes 控制大结果。
- 引擎说明：statementTimeoutMs、maxCost、maxPoolSize、connectionTimeoutMs、requireSsl 和 schemas 适用于网络引擎（PostgreSQL/MySQL）；SQLite 为本地文件，忽略这些设置；行数上限、列/表访问控制和掩码适用于所有引擎。
