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

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

更多关于 pg-mcp 项目的信息，请参考：

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

概述

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

该实现基于并扩展了 参考 PostgreSQL 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

使用方法

安装完成后的使用说明

1. 启动服务器：

   python -m server.app
   

2. 访问 API 文档： 打开浏览器，访问 http://localhost:8000/docs 查看交互式 API 文档。

3. 使用命令行工具： 使用 pg_query 和 pg_explain 命令与数据库进行交互。

示例

# 执行查询
pg_query -H localhost -P 5432 -U postgres -d testdb -q "SELECT * FROM users LIMIT 10;"

# 分析执行计划
pg_explain -H localhost -P 5432 -U postgres -d testdb -q "SELECT COUNT(*) FROM orders;"

架构

PG-MCP 服务器采用分层架构设计，主要组件包括：

• Web 服务：基于 FastAPI 实现 RESTful API
• 数据库适配器：支持 PostgreSQL 的连接池和事务管理
• 查询解释器：集成 PostgreSQL 执行计划分析工具
• 文档生成：自动生成 API 文档（如 Swagger）

参考资料

1. FastAPI 官方文档
2. PostgreSQL 官方文档
3. 模型上下文协议 (MCP) 规范

以上为完整翻译内容，保留了所有技术细节和代码示例。