内容
# postgres-mcp
一个连接 Claude Desktop 到 PostgreSQL 数据库的 [MCP](https://modelcontextprotocol.io) 服务器，暴露直接查询工具和基于 [SQL-Surgeon](https://github.com/RachelHuangZW/SQL-Surgeon) 的 AI 查询优化管道。
## 功能
该项目将两层功能封装成一个 MCP 服务器：
**第一层 — 直接数据库工具：** Claude 可以执行 SQL，检查执行计划，并查询 PostgreSQL 数据库的表模式。
**第二层 — AI 查询优化管道：** Claude 可以调用一个多步骤的 LangGraph 代理（SQL-Surgeon），它分析慢查询，识别性能瓶颈，生成优化建议，自我审查建议的质量，并可选地在沙箱模式中基准测试结果。
MCP 接口意味着 Claude 根据用户的问题决定使用哪个工具 — 无需手动选择工具。
## 架构
```
Claude Desktop
│
│ MCP 协议
▼
server.py ← 工具注册 + MCP 入口点
│
tools.py ← 工具逻辑
│
┌───┴────────────────────────┐
│ │
db.py agent/graph.py
（直接数据库连接） （LangGraph 管道）
│
┌──────────────┼──────────────┐
▼ ▼ ▼
run_explain identify_issues generate_advice
│ │ │
└──────────────┴──────────────┘
│
review_advice ←─── 重试循环（最多 2 次）
│
generate_benchmark_schema （可选）
```
## MCP 工具
| 工具 | 参数 | 描述 |
|------|------------|-------------|
| `execute_query` | `sql` | 运行任意 SQL；SELECT 返回 JSON 行，DML 返回受影响的行数 |
| `explain_query` | `sql`，`analyze` （布尔值，默认为 `false`） | 获取查询执行计划；`analyze=true` 运行 `EXPLAIN (ANALYZE, BUFFERS)` |
| `get_table_schema` | `table_name`，`schema` （默认为 `"public"`） | 列出列、类型、空值性、默认值和索引 |
| `analyze_query` | `sql`，`ddl`，`table_name` （可选） | 运行完整的 SQL-Surgeon 优化管道；返回问题、建议、优化 SQL 和可选基准测试 |
## SQL-Surgeon 管道
`analyze_query` 调用一个 5 节点的 LangGraph 图：
1. **run_explain** — 对真实数据库执行 `EXPLAIN (ANALYZE, COSTS, VERBOSE, BUFFERS, FORMAT JSON)`
2. **identify_issues** — 将执行计划 + DDL 发送到 Gemini 2.5 Pro；返回已识别的瓶颈的 JSON 数组（缺少索引、顺序扫描、行数估计错误等）
3. **generate_advice** — 生成特定的优化建议和完整的优化 SQL 脚本（索引 DDL + 重写查询）
4. **review_advice** — 第二个 LLM 调用，作为高级 DBA 审查员；返回 `pass` 或 `retry`，并带有反馈；最多重试 2 次
5. **generate_benchmark_schema** （可选） — 克隆目标表到临时模式，应用建议的 DDL，并重新运行 EXPLAIN 以比较计划
## 项目布局
```
src/postgres_mcp/
server.py # MCP 入口点，工具注册
tools.py # 工具逻辑；调用 db.py 和 agent/
db.py # 连接助手（读取 DATABASE_URL）
db_client.py # 代理管道使用的 DBClient
agent/
graph.py # LangGraph 图定义
nodes.py # 5 个节点函数
state.py # AgentState TypedDict
prompts.py # 每个 LLM 节点的系统提示
tests/
test_tools.py # 使用模拟数据库连接的单元测试
examples/
claude_desktop_config.json
```
## 设置
### 先决条件
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) — `brew install uv`
- 运行的 PostgreSQL 实例
- [Claude Desktop](https://claude.ai/download)
- Google API 密钥（Gemini 2.5 Pro）用于 `analyze_query`
### 安装
```bash
git clone https://github.com/RachelHuangZW/postgres-mcp
cd postgres-mcp
uv sync
```
### 配置环境
在项目根目录中创建 `.env`：
```
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
GOOGLE_API_KEY=your-google-api-key
```
### 在 Claude Desktop 中注册
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"postgres-mcp": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/postgres-mcp",
"--env-file", "/path/to/postgres-mcp/.env",
"python", "-m", "postgres_mcp.server"
]
}
}
}
```
保存后完全退出并重新打开 Claude Desktop。
### 验证
打开 Claude Desktop 并询问：
> “您有哪些可用的 MCP 工具？”
Claude 应该列出所有四个工具。
## 开发
```bash
uv sync --group dev
uv run pytest
```
测试使用模拟数据库连接，不需要运行的 PostgreSQL 实例。
## 技术栈
- **MCP 框架：** [FastMCP](https://github.com/jlowin/fastmcp)
- **代理框架：** [LangGraph](https://github.com/langchain-ai/langgraph)
- **LLM：** Gemini 2.5 Pro via `langchain-google-genai`
- **数据库：** PostgreSQL via `psycopg2`
- **包管理器：** uv
## 如何构建
该项目是与 Claude Code 合作构建的，使用 AI 协助进行配对编程。我设计了架构（两层工具暴露，`db.py` 与 `db_client.py` 的分离），做出了所有技术决策（MCP 框架选择，LangGraph 集成方法，安全边界），并在 AI 协助下迭代实现。README 中的每个设计决策都反映了我对 MCP 服务器设计和企业数据库工具暴露的思考。
## 安全注意事项
`execute_query` 运行任意 SQL。在生产环境中使用只读数据库角色或仅限受信任用户访问。
