PostgreSQL Model Context Protocol (PG-MCP) Server

PostgreSQL 模型上下文协议（PG-MCP）服务

为 PostgreSQL 数据库提供的模型上下文协议（MCP）服务，具备面向 AI Agent 的增强功能。

概述

PG-MCP 是面向 PostgreSQL 数据库的 模型上下文协议 服务实现。它通过 MCP 面向资源的架构，为 AI Agent 提供全面的 API，以发现、连接、查询和了解 PostgreSQL 数据库。

此实现基于 Postgres MCP 参考实现构建并进行了扩展，新增了多项重要功能：

1. 完整的服务实现：构建为支持 SSE 传输的完整服务，可用于生产环境
2. 多数据库支持：可同时连接多个 PostgreSQL 数据库
3. 丰富的目录信息：从数据库目录中提取并公开表和列的描述
4. 扩展上下文：提供基于 YAML 的详细知识，介绍 PostGIS 和 pgvector 等 PostgreSQL 扩展
5. 查询解释：提供专用工具，用于分析查询执行计划
6. 稳健的连接管理：提供完善的数据库连接生命周期管理，并安全处理连接 ID

功能

连接管理

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

查询工具

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

架构发现资源

• 列出包含描述的架构
• 列出包含描述和行数的表
• 获取包含数据类型和描述的列详情
• 查看表约束和索引
• 探索数据库扩展

数据访问资源

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

扩展上下文

内置以下 PostgreSQL 扩展的上下文信息：

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

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

安装

先决条件

• Python 3.13+
• PostgreSQL 数据库

使用 Docker

# Clone the repository
git clone https://github.com/stuzero/pg-mcp.git
cd pg-mcp

# Build and run with Docker Compose
docker-compose up -d

手动安装

# Clone the repository
git clone https://github.com/stuzero/pg-mcp.git
cd pg-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install using uv
uv sync --frozen

# Run the server
python -m server.app

用法

测试服务

仓库中包含用于验证服务功能的测试脚本：

# Basic server functionality test
python test.py "postgresql://username:password@hostname:port/database"

# Claude-powered natural language to SQL conversion
python client/claude_cli.py "Show me the top 5 customers by total sales"

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

# .env file
DATABASE_URL=postgresql://username:password@hostname:port/database
ANTHROPIC_API_KEY=your-anthropic-api-key
PG_MCP_URL=http://localhost:8000/sse

面向 AI Agent

供 Agent 使用的提示词示例：

Use the PostgreSQL MCP server to analyze the database. 
Available tools:
- connect: Register a database connection string and get a connection ID
- disconnect: Close a database connection
- pg_query: Execute SQL queries using a connection ID
- pg_explain: Get query execution plans

You can explore schema resources via:
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 扩展上下文文件
• 添加更多架构内省资源
• 提供查询优化建议