关键词

PostgreSQL自然语言查询AI数据库连接SQL生成数据流式处理

项目简介

PGMCP（PostgreSQL Model Context Protocol Server）旨在将AI助手与PostgreSQL数据库无缝连接。它允许用户使用自然语言提问，自动将其翻译成安全的、只读的SQL查询，并返回结构化的数据结果。PGMCP支持自动数据流处理和强大的错误处理机制，与Cursor、Claude Desktop等多种MCP兼容客户端协同工作。

主要功能点

  • 自然语言转SQL: 将用户的英文提问智能转换为PostgreSQL查询。
  • 自动流式传输: 自动处理和传输大量查询结果。
  • 安全只读访问: 确保所有生成的SQL查询都是只读操作，防止数据修改。
  • 文本搜索: 提供跨所有文本列的自由文本搜索功能。
  • 多格式输出: 支持表格、JSON和CSV等多种结果输出格式。
  • 智能错误处理: 当AI生成不正确SQL时，提供友好的错误提示和操作建议。
  • 生产级安全: 包含输入验证、SQL注入防护、查询超时和审计日志等安全措施。

安装步骤

  1. 准备环境:

    • Go 1.23+ 环境。
    • 一个可用的PostgreSQL数据库实例。
    • （可选）一个OpenAI API Key，用于SQL生成。

  2. 构建程序: 在项目根目录运行以下命令编译服务器和客户端程序：

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

  3. 配置数据库: 设置 'DATABASE_URL' 环境变量以连接到您的PostgreSQL数据库。例如：

    export DATABASE_URL="postgres://user:password@localhost:5432/mydb"

    如果您需要一个示例数据库，可以运行：

    psql $DATABASE_URL < schema.sql

  4. 运行服务器: 设置 OpenAI API Key（如果您选择使用OpenAI），然后启动PGMCP服务器：

    export OPENAI_API_KEY="您的OpenAI API Key" # 如果使用其他兼容API可省略或替换
./pgmcp-server

    服务器默认监听 'http://127.0.0.1:8080/mcp/sse'。

MCP服务器配置（用于MCP客户端）

MCP客户端通过JSON-RPC协议与PGMCP服务器通信。以下是配置您的MCP客户端（例如Cursor, Claude Desktop, VS Code扩展等）连接到PGMCP服务器的JSON格式配置示例。

{
  "pgmcp": {
    "command": "curl",
    "args": [
      "-N",
      "-H", "Accept: text/event-stream",
      "http://localhost:8080/mcp/sse",
      "<可选：-H 'Authorization: Bearer 您的身份验证令牌'>",
      "<可选：-H 'User-Agent: YourClientName'>",
      "<!-- -N 禁用缓冲，确保实时事件流 -->",
      "<!-- -H 设置HTTP头，Accept用于SSE，Authorization用于Bearer Token认证 -->"
    ]
  }
}

配置说明:

  • 'pgmcp': 这是您为MCP服务器定义的名称，可自定义。
  • 'command': 启动与PGMCP服务器通信的命令行工具。通常使用 'curl'。
  • 'args': 传递给 'command' 的参数列表。
    • '-N': (curl 参数) 禁用缓冲，确保服务器发送的事件实时到达客户端。
    • '-H "Accept: text/event-stream"': 设置HTTP 'Accept' 头，声明客户端期望服务器发送Server-Sent Events (SSE)流。
    • 'http://localhost:8080/mcp/sse': 这是PGMCP服务器的默认SSE端点URL。如果服务器运行在不同地址或端口，请相应修改。
    • ''Authorization: Bearer 您的身份验证令牌'': (可选) 如果PGMCP服务器配置了 'AUTH_BEARER' 环境变量，客户端需要通过此HTTP头发送匹配的身份验证令牌。请将 '您的身份验证令牌' 替换为实际的令牌。
    • ''User-Agent: YourClientName'': (可选) 用于标识客户端的User-Agent字符串。

基本使用方法

使用提供的客户端程序 'pgmcp-client' 进行测试和交互：

# 提出自然语言问题，以表格形式显示结果
./pgmcp-client -ask "What are the top 5 customers?" -format table

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

# 同时提出多个问题
./pgmcp-client -ask "Show tables" -ask "Count users" -format table

# 将所有数据导出为CSV格式（限制1000行）
./pgmcp-client -ask "Export all data" -format csv -max-rows 1000

信息

分类

数据库与文件

访问项目