Postgres MCP Server (Postgres MCP Pro)

什么是 Postgres MCP Server (Postgres MCP Pro)？

Postgres MCP Pro 是 Crystal DBA 推出的开源 postgres mcp server，为 AI 智能体提供面向 PostgreSQL 的安全 SQL 执行、schema 智能、EXPLAIN 执行计划、数据库健康检查和索引调优。

它不只是对数据库连接的简单封装。除了执行查询，它还提供用于性能优化的确定性工具：借助 pg_stat_statements 找出慢查询，借助 hypopg 模拟假设索引，并为你的工作负载搜索合适的索引配置。受限的只读访问模式让它也可以用于生产数据库。它采用 MIT 许可证，在 PyPI 上以 postgres-mcp 发布，在 Docker Hub 上以 crystaldba/postgres-mcp 发布，同时支持 stdio 和 SSE 两种传输方式。

如何使用 Postgres MCP Server (Postgres MCP Pro)？

前提条件：一个 PostgreSQL 连接 URI（先用 psql 或 pgAdmin 确认它可用），以及 Docker 或 Python 3.12+。维护者通常推荐 Docker，因为 Python 安装更容易遇到与环境相关的问题。

选择一种方式安装：

docker pull crystaldba/postgres-mcp
# or
pipx install postgres-mcp
# or
uv pip install postgres-mcp

选择访问模式：--access-mode=unrestricted 允许对数据和 schema 进行完整读写（用于开发环境）；--access-mode=restricted 将智能体限制在只读事务中，并限制执行时间（用于生产环境）。

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%/Claude/claude_desktop_config.json）。使用 Docker 时：

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

Docker 镜像会自动重映射 localhost（macOS/Windows 上使用 host.docker.internal，Linux 上使用 172.17.0.1 或合适的主机地址）。改用 uvx 时：

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

如果用 pipx 安装，使用 "command": "postgres-mcp"；如果用 uv，使用 "command": "uv" 和 "args": ["run", "postgres-mcp", "--access-mode=unrestricted"]。

Claude Code

用 Claude Code CLI 添加同样的 stdio 命令：

claude mcp add postgres \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  -- uvx postgres-mcp --access-mode=restricted

Cursor

从命令面板打开 Cursor Settings，进入 MCP 标签页，粘贴上面任意一个 mcpServers 配置块。Windsurf（Open Windsurf Settings Page）、Goose（goose configure → Add Extension）和 Qodo Gen 也使用相同的配置。

SSE 传输（共享或远程服务器）

使用 --transport=sse 启动服务器：

docker run -p 8000:8000 \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

然后在 Cursor（mcp.json）或 Cline 中用 {"type": "sse", "url": "http://localhost:8000/sse"} 指向它。Windsurf 使用 serverUrl 而不是 url。

可选扩展

如需索引调优和工作负载分析，请启用 pg_stat_statements 和 hypopg。在 AWS RDS、Azure 或 Google Cloud SQL 等托管服务上，它们通常已经可用：

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;

Postgres MCP Server (Postgres MCP Pro) 的主要功能

• 数据库健康检查：索引健康（重复、未使用、无效索引）、连接使用率、缓冲区缓存命中率、vacuum 健康、序列上限、约束校验和复制延迟。
• 基于 Microsoft Anytime 算法实现的索引调优，探索大量候选索引，并在性能收益与存储成本之间权衡。
• EXPLAIN 执行计划，并可在真正创建索引之前模拟假设索引的效果。
• schema 智能，支持基于上下文生成 SQL。
• 安全的 SQL 执行，提供 restricted（只读）和 unrestricted 两种访问模式，并进行安全的 SQL 解析。
• 所有功能都以 MCP 工具（而不是 resources）的形式提供，客户端兼容性更好。
• 支持 stdio 和 SSE 传输；可通过 Docker 或 Python 安装。

Postgres MCP Server (Postgres MCP Pro) 工具

• schema 浏览： list_schemas、list_objects（表、视图、序列、扩展）和 get_object_details（列、约束、索引）。
• 查询执行： execute_sql，在 restricted 模式下为只读。
• 查询计划： explain_query 返回执行计划，并可包含假设索引。
• 性能分析： get_top_queries 根据 pg_stat_statements 报告最慢的查询；analyze_workload_indexes 为整个工作负载推荐索引；analyze_query_indexes 为最多 10 条指定查询推荐索引。
• 健康： analyze_db_health 运行全部健康检查。

Postgres MCP Server (Postgres MCP Pro) 的使用场景

• 健康检查："Check the health of my database and identify any issues."
• 排查慢查询："What are the slowest queries in my database? And how can I speed them up?"
• 索引建议："Analyze my database workload and suggest indexes to improve performance."
• 优化查询："Help me optimize this query: SELECT * FROM orders JOIN customers ON ..."
• 在编辑器中修复 ORM 性能问题：项目的演示中，用 Cursor 修复了一个生成应用里缓慢的 SQLAlchemy 查询。
• 基于 schema 的开发：探索陌生的 schema，并生成与之匹配的 SQL。

Postgres MCP Server (Postgres MCP Pro) 与替代方案对比

• 参考版 PostgreSQL MCP 服务器：Model Context Protocol 最初的参考服务器，现已移入归档服务器仓库。它通过 MCP resources 暴露 schema，且只能执行只读查询。Postgres MCP Pro 使用工具，并增加了健康检查、EXPLAIN 分析和索引调优。
• Supabase MCP Server：为 Supabase 项目提供 Supabase 管理功能，而不是通用的 PostgreSQL 性能调优。
• 其他社区 postgresql mcp 服务器（其中有好几个也叫 postgres-mcp）主要用于执行查询和列出表。安装前请核对包名和作者。

Postgres MCP Server (Postgres MCP Pro) 常见问题排查

• Docker 中无法连接本地数据库：镜像会重映射 localhost，但请先在主机上用 psql 确认 URI 可用，并确认 Postgres 接受来自 Docker 网络的连接。
• 索引调优或慢查询工具报错：安装 pg_stat_statements 和 hypopg。在自行管理的 Postgres 上，pg_stat_statements 必须列在 shared_preload_libraries 中，hypopg 可能需要通过系统包安装。
• 写操作被拒绝：服务器处于 restricted 模式。只在开发环境中切换到 --access-mode=unrestricted。
• Python 安装出错：需要 Python 3.12+；可以改用 Docker 镜像。
• SSE 客户端无法连接：确认容器发布了端口（-p 8000:8000），客户端使用 /sse 路径；Windsurf 需要使用 serverUrl。