Postgres Query MCP

一个面向本地开发的、只读 PostgreSQL MCP Server。它把自然语言转换为 SQL，并在服务端强制执行数据库路由、表列白名单、危险 SQL 拦截、执行前 EXPLAIN、超时和限流。

快速开始

cp .env.example .env
uv sync --all-groups
uv run python -m pgmcp.main

默认策略已连接到本机正在运行的 Postgres 15.18：

postgresql://postgres:postgres@127.0.0.1:5432/db_query_demo

它包含 users 和 orders 表。服务层会拦截写操作及 users.email；在生产环境应改用独立只读账号。若需要启动仓库自带的隔离演示数据库，执行 docker compose up -d，再将连接串改为 postgresql://pgmcp_reader:pgmcp_reader@127.0.0.1:5433/db_query_demo。

配置 MCP 客户端时，使用：

{
  "mcpServers": {
    "postgres-query": {
      "command": "uv",
      "args": ["run", "python", "-m", "pgmcp.main"],
      "cwd": "/absolute/path/to/pgmcp"
    }
  }
}

未设置 PGMCP_OPENAI_API_KEY 时，服务仍可启动和提供 Schema 工具；调用 query 会返回明确的配置错误。服务兼容 OpenAI 格式的 API。使用 DeepSeek 时，在 MCP 环境变量中设置：

PGMCP_OPENAI_API_KEY=<你的 DeepSeek API Key>
PGMCP_OPENAI_BASE_URL=https://api.deepseek.com
PGMCP_OPENAI_MODEL=deepseek-v4-flash

MCP 工具

• list_databases：可查询数据库列表。
• describe_table：读取受允许的表结构。
• refresh_schema：刷新目标数据库的内存 Schema 缓存。
• query：自然语言查询，output_mode 可选 sql 或 result。

验证

uv run pytest
uv run ruff check .

Prometheus 指标默认暴露在 http://127.0.0.1:9464/metrics。详细范围和阶段说明见 项目计划。

多数据库端到端测试

隔离 Docker 环境会创建 db_query_demo 和 reporting_demo 两个数据库。它们使用同一个只读角色，但策略允许访问的表完全不同。

docker compose up -d
PGMCP_RUN_INTEGRATION=1 uv run pytest -m integration -q

测试会验证两个数据库的正常查询、跨库对象访问被拒绝，以及未知数据库被拒绝；固定 SQL 生成器让这些测试不依赖 OpenAI API Key。