PostgreSQL 模型上下文协议 (PG-MCP) 服务器

针对 PostgreSQL 数据库的增强版 AI 代理模型上下文协议 (MCP) 服务器。

更多关于 pg-mcp 项目的详情，请访问：

https://stuzero.github.io/pg-mcp/

概述

PG-MCP 是一个用于 PostgreSQL 数据库的 模型上下文协议 的服务器实现。它提供了一个全面的 API，使 AI 代理能够通过 MCP 的资源导向架构发现、连接、查询并理解 PostgreSQL 数据库。

此实现基于并扩展了 参考 Postgres MCP 实现，具有以下关键增强功能：

1. 完整的服务器实现：作为带有 SSE 传输的生产用途完整服务器构建
2. 多数据库支持：同时连接多个 PostgreSQL 数据库
3. 丰富的目录信息：从数据库目录中提取并暴露表/列描述
4. 扩展上下文：提供关于 PostgreSQL 扩展（如 PostGIS 和 pgvector）的详细 YAML 基础知识
5. 查询解释：包含一个专门用于分析查询执行计划的工具
6. 强大的连接管理：数据库连接的生命周期管理，安全处理连接 ID

功能

连接管理

• 连接工具：注册 PostgreSQL 连接字符串并获取安全的连接 ID
• 断开连接工具：显式关闭数据库连接
• 连接池：高效的连接管理

查询工具

• pg_query：使用连接 ID 执行只读 SQL 查询
• pg_explain：以 JSON 格式分析查询执行计划

架构发现资源

• 列出带有描述的架构
• 列出带有描述和行数的表
• 获取带有数据类型和描述的列细节
• 查看表约束和索引
• 探索数据库扩展

数据访问资源

• 表数据样本（带分页）
• 获取近似行数

扩展上下文

内置的 PostgreSQL 扩展上下文信息，例如：

• PostGIS：空间数据类型、函数和示例
• pgvector：向量相似性搜索函数和最佳实践

可以通过 YAML 配置文件轻松添加其他扩展。

安装

先决条件

• Python 3.13+
• PostgreSQL 数据库

使用 Docker

# 克隆仓库
git clone https://github.com/stuzero/pg-mcp-server.git
cd pg-mcp-server

# 使用 Docker Compose 构建并运行
docker-compose up -d

手动安装

# 克隆仓库
git clone https://github.com/stuzero/pg-mcp-server.git
cd pg-mcp-server

# 安装依赖项并创建虚拟环境 (.venv)
uv sync

# 激活虚拟环境
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 运行服务器
python -m server.app

使用

测试服务器

仓库中包含测试脚本以验证服务器功能：

# 基本服务器功能测试
python test.py "postgresql://用户名:密码@主机名:端口/数据库"

# 使用 Claude 的自然语言到 SQL 转换
python example-clients/claude_cli.py "按总销售额显示前五名客户"

claude_cli.py 脚本需要环境变量：

# .env 文件
DATABASE_URL=postgresql://用户名:密码@主机名:端口/数据库
ANTHROPIC_API_KEY=你的 anthropic api 密钥
PG_MCP_URL=http://localhost:8000/sse

对于 AI 代理

用于代理的示例提示：

使用 PostgreSQL MCP 服务器分析数据库。
可用工具：
- connect：注册数据库连接字符串并获取连接 ID
- disconnect：关闭数据库连接
- pg_query：使用连接 ID 执行 SQL 查询
- pg_explain：获取查询执行计划

你可以通过以下方式探索架构资源：
pgmcp://{conn_id}/schemas
pgmcp://{conn_id}/schemas/{schema}/tables
pgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns

完整的数据库描述可以在以下资源中找到：
pgmcp://{conn_id}/

架构

此服务器基于：

• MCP：模型上下文协议基础
• FastMCP：Python MCP 库
• asyncpg：异步 PostgreSQL 客户端
• YAML：用于扩展上下文信息

安全考虑

• 服务器默认以只读模式运行（通过事务设置强制执行）
• 连接详情在资源 URL 中不会暴露，仅使用不透明的连接 ID
• 数据库凭据只需在初始连接时发送一次

贡献

欢迎贡献！扩展领域包括：

• 更多的 PostgreSQL 扩展上下文文件
• 更多的架构内省资源
• 查询优化建议