PGMCP - PostgreSQL 模型上下文协议服务器

PGMCP 通过自然语言查询将 AI 助手连接到 任何 PostgreSQL 数据库。用简单的英语提问，即可获得结构化的 SQL 查询结果，并支持自动流式传输和强大的错误处理机制。

兼容平台：Cursor、Claude Desktop、VS Code 扩展以及任何 MCP 兼容客户端

快速入门

PGMCP 可以连接到 您现有的 PostgreSQL 数据库，并通过自然语言查询使其对 AI 助手开放。

前提条件

• PostgreSQL 数据库（包含您模式的现有数据库）
• OpenAI API 密钥（可选，用于 AI 驱动的 SQL 生成）

基本使用方法

# 设置环境变量
export DATABASE_URL="postgres://user:password@localhost:5432/your-existing-db"
export OPENAI_API_KEY="your-api-key"  # 可选

# 运行服务器（使用预编译的二进制文件）
./pgmcp-server

# 在另一个终端中使用客户端进行测试
./pgmcp-client -ask "What tables do I have?" -format table
./pgmcp-client -ask "Who is the customer that has placed the most orders?" -format table
./pgmcp-client -search "john" -format table

其工作流程如下：

👤 用户 / AI 助手
         │
         │ “谁是顶级客户？”
         ▼
┌─────────────────────────────────────────────────────────────┐
│                    任意 MCP 客户端                           │
│                                                             │
│  PGMCP CLI  │  Cursor  │  Claude Desktop  │  VS Code  │ ... │
│  JSON/CSV   │  聊天    │  AI 助手        │  编辑器   │     │
└─────────────────────────────────────────────────────────────┘
         │
         │ 流式 HTTP / MCP 协议
         ▼
┌─────────────────────────────────────────────────────────────┐
│                    PGMCP 服务器                             │
│                                                             │
│  🔒 安全    🧠 AI 引擎      🌊 流式传输               │
│  • 输入验证  • 模式缓存    • 自动分页         │
│  • 审计日志  • OpenAI API  • 内存管理       │
│  • SQL 防护  • 错误恢复    • 连接池         │
└─────────────────────────────────────────────────────────────┘
         │
         │ 只读 SQL 查询
         ▼
┌─────────────────────────────────────────────────────────────┐
│                您的 PostgreSQL 数据库                     │
│                                                             │
│  任意模式：电商、分析、CRM 等                               │
│  表 • 视图 • 索引 • 函数                                   │
└─────────────────────────────────────────────────────────────┘

外部 AI 服务：
OpenAI API • Anthropic • 本地 LLM（Ollama 等）

主要优势：
✅ 适用于任何 PostgreSQL 数据库（无需假设模式）
✅ 无需修改模式  
✅ 只读访问（100% 安全）
✅ 自动流式传输大型结果
✅ 智能查询理解（单数与复数区分）
✅ 强大的错误处理机制（优雅的 AI 故障恢复）
✅ 支持 PostgreSQL 的大小写敏感性（混合大小写表名）
✅ 生产级安全性和性能
✅ 通用数据库兼容性
✅ 多种输出格式（表格、JSON、CSV）
✅ 全文搜索功能，可跨所有列
✅ 支持身份验证
✅ 全面的测试套件

功能特性

• 自然语言转 SQL：用简单英语提问
• 自动流式传输：自动处理大型结果集
• 安全只读访问：防止任何写操作
• 全文搜索：可在所有文本列中搜索
• 多种输出格式：表格、JSON 和 CSV
• PostgreSQL 大小写敏感性：正确处理混合大小写表名
• 通用兼容性：适用于任何 PostgreSQL 数据库

环境变量

必填：

• DATABASE_URL：指向您现有数据库的 PostgreSQL 连接字符串

可选：

• OPENAI_API_KEY：用于 AI 驱动的 SQL 生成的 OpenAI API 密钥
• OPENAI_MODEL：使用的模型（默认为“gpt-4o-mini”）
• HTTP_ADDR：服务器地址（默认为“:8080”）
• HTTP_PATH：MCP 端点路径（默认为“/mcp”）
• AUTH_BEARER：用于身份验证的 Bearer 令牌

安装

下载预编译二进制文件

1. 访问 GitHub 发布页面
2. 下载适合您平台的二进制文件（Linux、macOS、Windows）
3. 解压并运行：

# macOS/Linux 示例
tar xzf pgmcp_*.tar.gz
cd pgmcp_*
./pgmcp-server

其他安装方式

# Homebrew（macOS/Linux） - 第一次发布后可用
brew tap subnetmarco/homebrew-tap
brew install pgmcp

# 从源码构建
go build -o pgmcp-server ./server
go build -o pgmcp-client ./client

Docker/Kubernetes

# Docker
docker run -e DATABASE_URL="postgres://user:pass@host:5432/db" \
  -p 8080:8080 ghcr.io/subnetmarco/pgmcp:latest

# Kubernetes（完整清单请参见 examples/ 目录）
kubectl create secret generic pgmcp-secret \
  --from-literal=database-url="postgres://user:pass@host:5432/db"
kubectl apply -f examples/k8s/

快速开始

# 设置数据库（可选 - 适用于任何现有 PostgreSQL 数据库）
export DATABASE_URL="postgres://user:password@localhost:5432/mydb"
psql $DATABASE_URL < schema.sql

# 运行服务器
export OPENAI_API_KEY="your-api-key"
./pgmcp-server

# 使用客户端测试
./pgmcp-client -ask "Who is the user that places the most orders?" -format table
./pgmcp-client -ask "Show me the top 40 most reviewed items in the marketplace" -format table

环境变量

必填：

• DATABASE_URL：PostgreSQL 连接字符串

可选：

• OPENAI_API_KEY：用于 SQL 生成的 OpenAI API 密钥
• OPENAI_MODEL：使用的模型（默认为“gpt-4o-mini”）
• HTTP_ADDR：服务器地址（默认为“:8080”）
• HTTP_PATH：MCP 端点路径（默认为“/mcp”）
• AUTH_BEARER：用于身份验证的 Bearer 令牌

使用示例

# 用自然语言提问
./pgmcp-client -ask "What are the top 5 customers?" -format table
./pgmcp-client -ask "How many orders were placed today?" -format json

# 在所有文本字段中搜索
./pgmcp-client -search "john" -format table

# 一次性执行多个查询
./pgmcp-client -ask "Show tables" -ask "Count users" -format table

# 不同的输出格式
./pgmcp-client -ask "Export all data" -format csv -max-rows 1000

示例数据库

该项目包含两个模式：

• schema.sql：完整的类亚马逊式电商平台，包含 5,000 多条记录
• schema_minimal.sql：最小化的测试模式，其中 Categories 表名采用大小写混合形式

主要特性：

• 大小写混合的表名（如 "Categories"），用于测试大小写敏感性
• 复合主键（如 order_items），用于检验 AI 的假设
• 真实的表间关系和数据类型

使用您自己的数据库：

export DATABASE_URL="postgres://user:pass@host:5432/your_db"
./pgmcp-server
./pgmcp-client -ask "What tables do I have?"

AI 错误处理

当 AI 生成错误的 SQL 语句时，PGMCP 会以优雅的方式进行处理：

{
  "error": "生成的查询中未找到列",
  "suggestion": "请尝试重新表述问题，或询问特定的表",
  "original_sql": "SELECT non_existent_column FROM table..."
}

系统不会崩溃，而是提供有用的反馈并继续运行。

MCP 集成

Cursor 集成

# 启动服务器
export DATABASE_URL="postgres://user:pass@localhost:5432/your_db"
./pgmcp-server

在 Cursor 设置中添加：

{
  "mcp.servers": {
    "pgmcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}

Claude Desktop 集成

编辑 ~/.config/claude-desktop/claude_desktop_config.json：

{
  "mcpServers": {
    "pgmcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}

API 工具

• ask：自然语言问题 → 自动流式传输的 SQL 查询
• search：跨所有数据库文本列的自由文本搜索
• stream：针对超大数据集的高级流式传输，并支持分页

安全特性

• 只读强制执行：阻止写操作（INSERT、UPDATE、DELETE 等）
• 查询超时：防止长时间运行的查询
• 输入验证：对所有用户输入进行清理和验证
• 事务隔离：所有查询均在只读事务中执行

测试

# 单元测试
go test ./server -v

# 集成测试（需要 PostgreSQL）
go test ./server -tags=integration -v

许可证

Apache 2.0 - 详情请参阅 LICENSE 文件。

相关项目

• 模型上下文协议 - 底层协议规范
• MCP Go SDK - MCP 的 Go 实现

---

PGMCP 通过自然语言使您的 PostgreSQL 数据库能够被 AI 助手访问，同时通过只读访问控制确保安全性。

PGMCP 快速上手指南

PGMCP 是一个基于 Model Context Protocol (MCP) 的 PostgreSQL 服务器，允许 AI 助手（如 Cursor、Claude Desktop）通过自然语言直接查询你的 PostgreSQL 数据库。它支持自动流式传输、只读安全访问以及多种输出格式。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Linux, macOS 或 Windows。
• 数据库：一个现有的 PostgreSQL 数据库（无需修改表结构）。
• API 密钥（可选）：OpenAI API Key，用于启用 AI 驱动的 SQL 生成功能。如果不配置，部分智能查询功能可能受限。
• 网络：确保本地可以访问数据库端口（默认 5432）及 OpenAI 服务（如需使用 AI 功能）。

安装步骤

你可以通过下载预编译二进制文件或使用 Docker 快速部署。

方法一：下载预编译二进制文件（推荐）

1. 访问 GitHub Releases 页面。
2. 下载对应你操作系统的压缩包（pgmcp_*.tar.gz 或 .zip）。
3. 解压并运行：

# 以 macOS/Linux 为例
tar xzf pgmcp_*.tar.gz
cd pgmcp_*
# 赋予执行权限（如需）
chmod +x pgmcp-server pgmcp-client

方法二：从源码构建

如果你已安装 Go 环境：

go build -o pgmcp-server ./server
go build -o pgmcp-client ./client

方法三：使用 Docker

docker run -e DATABASE_URL="postgres://user:pass@host:5432/db" \
  -p 8080:8080 ghcr.io/subnetmarco/pgmcp:latest

基本使用

1. 配置环境变量

设置数据库连接字符串。如果需要 AI 生成 SQL，还需设置 OpenAI Key。

# 替换为你的实际数据库连接信息
export DATABASE_URL="postgres://user:password@localhost:5432/your-existing-db"

# 可选：设置 OpenAI API Key 以启用智能查询
export OPENAI_API_KEY="your-api-key"

2. 启动服务器

在终端中运行服务器：

./pgmcp-server

默认监听地址为 http://localhost:8080/mcp。

3. 测试查询

打开一个新的终端窗口，使用自带的客户端工具进行测试：

查询表结构：

./pgmcp-client -ask "What tables do I have?" -format table

自然语言提问（需配置 OPENAI_API_KEY）：

./pgmcp-client -ask "Who is the customer that has placed the most orders?" -format table

全文搜索：

./pgmcp-client -search "john" -format table

指定输出格式（JSON/CSV）：

./pgmcp-client -ask "How many orders were placed today?" -format json

4. 集成到 AI 编辑器（可选）

若要在 Cursor 或 Claude Desktop 中使用，请在其配置文件中添加 MCP 服务器信息：

Cursor 配置 (settings.json)：

{
  "mcp.servers": {
    "pgmcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}

Claude Desktop 配置 (claude_desktop_config.json)：

{
  "mcpServers": {
    "pgmcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}

配置完成后，即可在聊天窗口中直接用自然语言询问数据库内容。PGMCP 默认仅执行只读查询，确保数据安全。