database-mcp

SQL 数据库 MCP 服务器，具备真正的服务端结果分页——这是现有数据库 MCP 服务器都没有的功能（DBHub 限制行数，Google 的 MCP Toolbox 返回全部内容，mcp-alchemy 在 4000 字符处截断）。

PostgreSQL 参考实现。

为什么

每个现有的 SQL MCP 服务器要么截断大型结果，要么将整个结果转储到模型的上下文中。MCP 规范仅对 列表 操作（tools/list）进行分页，而不对工具结果进行分页。database-mcp 弥补了这一差距：

• 查询作为 PostgreSQL 服务端游标（DECLARE/FETCH FORWARD）在持有的事务中仅执行一次。

• 每次 fetch(cursor) 都精确地从上一页结束的位置继续——无需重新执行，无需 OFFSET 重新扫描，并且 MVCC 快照即使在并发写入下也能保持结果稳定。

• 页面受行数（page_size）和渲染字节数（max_page_bytes）限制；过大的单元格会被截断并带有显式标记。

• 持有的游标有界：最大 N 个并发（LRU 逐出）、TTL 空闲逐出，以及 idle_in_transaction_session_timeout 作为服务端兜底。耗尽的游标自动关闭。

Related MCP server: pgsql-mcp

连接配置文件——由 AI 在运行时管理

连接是命名的配置文件，持久化在 ~/.config/database-mcp/profiles.json（chmod 600）中。AI 可以通过工具即时添加、更改、测试和删除它们，无需重启服务器：

• profile_add(name, dsn, allow_writes=false, description, make_default, test=true)

• profile_remove(name) · profile_test(name) · profiles()

• 每个查询工具都接受可选的 profile 参数；省略时使用默认配置文件。

配置文件默认只读（会话级 default_transaction_read_only）；写入需要显式的 allow_writes=true 配置文件。

SSH 桥接

配置文件可以访问仅通过 SSH 可访问的数据库（经典的“Postgres 监听远程主机的 localhost”设置）：

profile_add(name="prod", dsn="postgresql://app@dbhost:5432/app",
            ssh_host="dbhost")

• 隧道是系统 ssh 子进程（-N -L、BatchMode、keepalives）——你的 ~/.ssh/config、密钥和代理不变地适用。认证必须以非交互方式工作。

• ssh_remote_host/ssh_remote_port 默认为 DSN 的主机/端口，从 SSH 主机看来；如果 DSN 主机等于 SSH 主机，则默认为 127.0.0.1（通常情况）。

• 隧道惰性启动，每次使用时进行健康检查，并自动重建。如果隧道在分页中途死亡，其游标会以明确的错误失效，下一次查询会重新连接。

• 隧道连接显式禁用多路复用（ControlMaster），因此隧道的生命周期恰好是子进程的生命周期。

工具

结果是紧凑的 JSON——列只出现一次，行作为数组——大约是其他服务器发出的行字典格式的 token 数的一半。query 还返回 estimated_rows（通过 EXPLAIN 的规划器估计），以便模型知道它正在分页进入什么。

安装与运行

uv pip install -e .
database-mcp --dsn postgresql://user@host:5432/db      # registers profile "default"
database-mcp                                           # start empty, add profiles at runtime

Claude Code 注册：

claude mcp add database -- database-mcp --dsn postgresql://user@host:5432/db

选项：--profiles FILE、--allow-writes、--page-size 50、 --max-page-size 500、--max-page-bytes 32000、--max-cell 400、 --cursor-ttl 300、--max-cursors 4、--statement-timeout 30、 --keepalive 120、--connect-timeout 5。 环境变量：DATABASE_MCP_DSN / DATABASE_URL、DATABASE_MCP_PROFILES。

陈旧连接处理

死连接在每一层都被快速检测到，而不是挂起：

• SSH 隧道：ServerAliveInterval = --keepalive（默认 2 分钟），ServerAliveCountMax=1——一次未收到的探测就会终止隧道进程，引擎管理器会在下次使用时检测到并惰性重建。

• 数据库连接：TCP keepalives（keepalives_idle = --keepalive，每 10 秒探测，3 次未响应）在约 30 秒内捕获死对端——包括连接池外固定的游标连接。

• 连接池检出检查：每个分发的连接都通过廉价的往返验证；过期的连接被丢弃并透明替换——调用者永远不会看到错误。空闲的池化连接在 --keepalive 秒后被回收；连接尝试在 --connect-timeout（默认 5 秒）后失败，而不是 TCP 默认的约 2 分钟。

测试

uv pip install -e '.[dev]'
pytest            # needs a local PostgreSQL (DBMCP_TEST_DSN to override)

许可证

MIT