postgres_mcp

用途

这是一个用于 PostgreSQL 数据库操作的 MCP 服务器，可与 Claude Code、Claude Desktop、Cursor 以及任何 MCP 兼容客户端配合使用。仓库同时包含 TypeScript 和 Python 两个实现版本，两者功能完全一致；TypeScript 版本用于 Smithery 部署。TypeScript 包需 Node.js 20+，Python 包需 Python 3.10+。

主要能力

• 查询执行：默认带只读保护地执行 SQL 查询。
• 模式探索：列出 schema、表、视图和函数。
• 表分析：描述结构、索引、约束与统计信息。
• 性能工具：EXPLAIN 查询并分析表健康状况。
• 安全优先：SQL 注入防护、凭据保护、默认只读。
• MCP Prompts：为探索、查询构建和文档编写提供引导式工作流。
• MCP Resources：以 markdown 形式提供可浏览的数据库结构。

使用方式

环境变量与多数据库

在实际工作中往往需要接触多个数据库。无需每次修改配置并重启客户端，可以声明多个连接，并在每次调用时通过别名选择：

• list_databases 返回已配置的别名及其主机、数据库名、写权限和默认连接。凭据不会被返回。
• 除 list_databases 外的每个工具都接受可选的 database 参数来指定别名。省略时使用默认连接，因此原有的单数据库配置无需任何改动即可继续工作。
• allowWrite 按连接设置，回退到 ALLOW_WRITE_OPERATIONS。生产副本保持只读，而本地数据库可允许写入。
• default: true 标记省略 database 时使用的连接；否则使用第一个声明的连接。最多只能有一个连接被标记为默认。
• 每个连接可接受离散字段（host、port、user、password、database、sslmode）或 url DSN；离散字段会覆盖 DSN，因此可以复用 URL 并只修改其中一部分。
• 每个别名一个连接池，惰性打开：已配置但未使用的数据库不会打开套接字。
• POSTGRES_CONNECTIONS 与普通 POSTGRES_* 变量互斥。当设置了前者时，后者会被忽略，因此不会出现哪个生效的疑问。
• 凭据只来自环境变量。database 参数命名的是别名；刻意不支持将主机、用户、密码或连接字符串作为工具参数传入，因为那会把机密带入对话中。这一点有测试来约束。

客户端配置

Claude Code CLI 以及 ~/.cursor/mcp.json 均可配置使用（资料中相关代码段未完整展示，故此处不展开具体 JSON 内容）。

可用工具（共 15 个）

以下每个工具（除 list_databases 外）都接受可选的 database 参数来命名已配置的连接。

• 查询执行
• 模式探索
• 性能与分析

引导式工作流与可浏览结构

提供帮助 Claude 有效协助的引导式工作流，以及可浏览的数据库结构。

适用场景

配置完成后，可以要求 Claude 执行以下任务：

模式探索：

• “列出 public schema 中的所有表”
• “描述 users 表的结构”
• “有哪些视图可用？”
• “显示 orders 表的前 10 行”
• “查找上周下过订单的所有客户”
• “按状态分组统计记录数”

性能分析：

• “orders 表上有哪些索引？”
• “分析 users 表的性能”
• “解释这个查询：SELECT * FROM orders WHERE created_at > '2024-01-01'”
• “为这个数据库生成数据字典”
• “哪些列的名字里包含 'email'？”

限制与安全

该 MCP 服务器实现了多层安全机制：

• 默认只读：除非通过 ALLOW_WRITE_OPERATIONS=true 显式启用，否则写操作（INSERT、UPDATE、DELETE）会被阻止。
• SQL 注入防护：所有查询在执行前都会校验；危险操作（如 DROP DATABASE 等）始终被阻止；不允许执行多条语句；SQL 注释被阻止。
• 凭据保护：密码使用安全字符串类型存储；凭据不会出现在日志或错误消息中；结果受 MAX_ROWS 限制（默认 1000）；查询超时可通过 QUERY_TIMEOUT 配置。

故障排查

• 连接问题
• 权限被拒绝：确保数据库用户拥有 SELECT 权限
• MCP 服务器无法连接

更多信息可参考安装指南与 GitHub 仓库。作者为 Javier Aguilar，一位专攻多智能体编排与 MCP 开发的 AI Agent 架构师。