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

一个针对 PostgreSQL 数据库的模型上下文协议 (MCP) 服务器，为 AI 代理提供了增强的功能。

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

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

概述

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

该实现基于并扩展了 参考的 Postgres MCP 实现，并引入了几项关键增强：

1. 完整的服务器实现：作为具有 SSE 传输的完整服务器构建，适用于生产环境
2. 多数据库支持：可同时连接多个 PostgreSQL 数据库
3. 丰富的元数据信息：从数据库目录中提取并暴露表和列的描述
4. 扩展上下文：提供基于 YAML 的详细 PostgreSQL 扩展知识，如 PostGIS 和 pgvector
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://username:password@hostname:port/database"

# Claude 驱动的自然语言到 SQL 转换
python example-clients/claude_cli.py "给我展示按总销售额排名前 5 的客户"

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

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

架构

该服务器基于以下技术构建：

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

安全考虑

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

贡献

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

• 添加更多 PostgreSQL 扩展的上下文文件
• 提供更多的模式内省资源
• 提供查询优化建议

pg-mcp-server 快速上手指南

pg-mcp-server 是一个基于 Model Context Protocol (MCP) 的 PostgreSQL 数据库服务器实现，专为 AI 智能体设计。它支持多数据库连接、丰富的元数据发现（表结构、注释）、查询执行计划分析以及 PostGIS/pgvector 等扩展的上下文增强。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.13 或更高版本
• 数据库：可访问的 PostgreSQL 数据库实例
• 包管理工具：推荐使用 uv 进行依赖管理（若未安装，可通过 pip install uv 获取）

安装步骤

您可以选择使用 Docker 快速部署，或通过手动方式在本地运行。

方式一：使用 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

# 使用 uv 同步依赖并创建虚拟环境 (.venv)
uv sync

# 激活虚拟环境
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 启动服务器
python -m server.app

提示：国内用户若遇到 git clone 或 uv sync 下载缓慢，可配置 Git 代理或使用国内 PyPI 镜像源（如清华源）加速依赖安装： uv pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple (如需手动指定)

基本使用

安装完成后，您可以通过内置脚本测试服务器功能，或直接将其集成到 AI 智能体中。

1. 功能测试

运行以下命令测试基础连接和查询功能（请替换为您的真实数据库连接字符串）：

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

2. 结合 Claude 智能体使用

项目提供了一个示例脚本，演示如何让 Claude 通过自然语言生成 SQL 并查询数据库。

首先，在项目根目录创建 .env 文件并配置环境变量：

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

然后运行示例客户端：

# 使用自然语言查询数据库
python example-clients/claude_cli.py "Show me the top 5 customers by total sales"

3. AI 智能体集成提示

若在自定义 Agent 中使用，可参考以下 Prompt 引导模型调用工具：

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}/

安全说明：服务器默认以只读模式运行，连接凭证仅在初始连接时传输，后续交互仅使用不透明的连接 ID，保障数据库安全。