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

一个用于 PostgreSQL 数据库的模型上下文协议 (MCP) 服务器，具有增强的 AI 代理功能。

概述

PG-MCP 是 模型上下文协议 的服务器实现，用于 PostgreSQL 数据库。 它为 AI 代理提供了一个全面的 API，通过 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.git
cd pg-mcp

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

手动安装

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

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 使用 uv 安装
uv sync --frozen

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

用法

测试服务器

该存储库包含用于验证服务器功能的测试脚本：

# 基本服务器功能测试
python test.py "postgresql://username:password@hostname:port/database"

# Claude 驱动的自然语言到 SQL 转换
python client/claude_cli.py "Show me the top 5 customers by total sales"

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

# .env 文件
DATABASE_URL=postgresql://username:password@hostname:port/database
ANTHROPIC_API_KEY=your-anthropic-api-key
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

架构

此服务器构建于：

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

安全注意事项

• 默认情况下，服务器以只读模式运行（通过事务设置强制执行）
• 连接详细信息永远不会在资源 URL 中公开，只有不透明的连接 ID
• 数据库凭据只需要在初始连接期间发送一次

贡献

欢迎贡献！ 扩展领域：

• 其他 PostgreSQL 扩展上下文文件
• 更多模式内省资源
• 查询优化建议