PostgreSQL Model Context Protocol (PG-MCP) Server

PostgreSQL Model Context Protocol（PG-MCP）服务

一个面向 PostgreSQL 数据库的 Model Context Protocol（MCP）服务，为 AI Agent 提供增强功能。

有关 pg-mcp 项目的更多信息，请访问：

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

概述

PG-MCP 是面向 PostgreSQL 数据库的 Model Context Protocol 服务实现。它基于 MCP 面向资源的架构，为 AI Agent 提供全面的 API，用于发现、连接、查询和了解 PostgreSQL 数据库。

此实现基于并扩展了 Postgres MCP 参考实现，并进行了多项重要增强：

1. 完整的服务实现：构建为完整的服务，采用 SSE 传输，可用于生产环境
2. 多数据库支持：可同时连接多个 PostgreSQL 数据库
3. 丰富的目录信息：从数据库目录中提取并公开表和列的说明
4. 扩展上下文：提供有关 PostGIS 和 pgvector 等 PostgreSQL 扩展的详细 YAML 知识
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-server.git
cd pg-mcp-server

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

手动安装

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

# Install dependencies and create a virtual environment ( .venv )
uv sync

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 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 example-clients/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

A comprehensive database description is available at this resource:
pgmcp://{conn_id}/

架构

此服务基于：

• MCP：Model Context Protocol 基础
• FastMCP：用于 MCP 的 Python 库
• asyncpg：异步 PostgreSQL 客户端
• YAML：用于扩展上下文信息

安全注意事项

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

贡献

欢迎贡献！可扩展的方向包括：

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