Neon PostgreSQL MCP Server

Neon PostgreSQL MCP 服务

一个模型上下文协议（MCP）服务，可安全访问 Neon PostgreSQL 数据库，让 Claude 等 AI 助手通过标准化工具与数据库交互。

概览

此 MCP 服务允许 AI 助手：

• 使用 SELECT 语句查询数据
• 执行数据修改（INSERT、UPDATE、DELETE）
• 列出可用表
• 描述表结构

此服务提供多个版本，展示不同的实现方式：

• pg-mcp-server.js - 使用最新 MCP SDK 的现代 ES 模块实现
• index.js - 基于类架构的 CommonJS 实现
• basic-pg-server.js - 使用基本 MCP 协议处理方式的简化实现
• src/index.ts - TypeScript 实现（需要编译）

功能

• 安全连接：与 Neon PostgreSQL 建立 SSL/TLS 加密连接
• 连接池：高效的数据库连接管理
• 类型安全：对所有操作进行输入验证
• 错误处理：全面的错误处理，并提供有意义的消息
• 符合 MCP 规范：完整实现模型上下文协议规范

前置条件

• Node.js 18+
• Neon PostgreSQL 数据库账户和连接字符串
• 兼容 MCP 的客户端（例如 Claude Desktop、Cursor IDE）

安装

1. 克隆此仓库：

git clone <repository-url>
cd neon-pg-server

2. 安装依赖：

npm install

3. 通过环境变量配置 Neon PostgreSQL 连接（见下文）：

export NEON_PG_CONNECTION_STRING="postgresql://user:password@host/database?sslmode=require"

环境变量

变量	必需	用途
NEON_PG_CONNECTION_STRING	三者之一	单个连接字符串，注册为名为 default 的项目。原有的单数据库配置仍受完整支持。
NEON_PG_CONNECTIONS	三者之一	将项目名称映射到连接字符串的 JSON 对象，例如 {"versemind":"postgresql://...","linecrush":"postgresql://..."}。可与 NEON_PG_CONNECTION_STRING 配合使用。
NEON_PG_CONNECTIONS_FILE	三者之一	JSON 文件的路径，文件中包含相同的名称 → 连接字符串映射。适用于在一台机器上的多个 MCP 注册配置中共享同一份连接映射（请勿将该文件纳入版本控制，例如 ~/.secrets/neon-connections.json）。
NEON_PG_READONLY_PROJECTS	否	以逗号分隔的项目名称列表；这些项目会直接拒绝 execute 工具调用（读取操作仍可用）。

前三项中至少有一项必须设置。配置来源按顺序合并：NEON_PG_CONNECTION_STRING（作为 default）、NEON_PG_CONNECTIONS_FILE，然后是 NEON_PG_CONNECTIONS；后面的来源会按名称覆盖前面的来源（覆盖时会向 stderr 记录警告）。

多项目配置

一个服务实例可以服务于多个 Neon 项目。连接池会在首次使用时按项目延迟创建，因此配置六个项目不会在启动时创建六个连接池。

{
  "neon-pg": {
    "command": "node",
    "args": ["/path/to/neon-pg-server/pg-mcp-server.js"],
    "env": {
      "NEON_PG_CONNECTION_STRING": "postgresql://user:[email protected]/verceldb?sslmode=require",
      "NEON_PG_CONNECTIONS": "{\"versemind\":\"postgresql://user:[email protected]/neondb?sslmode=require\",\"linecrush\":\"postgresql://user:[email protected]/verceldb?sslmode=require\"}",
      "NEON_PG_READONLY_PROJECTS": "linecrush"
    }
  }
}

使用此配置时：

• 不带参数的 get_tables 会针对 default（旧版连接字符串）运行——现有配置无需更改即可继续工作。
• 使用 project: "versemind" 的 get_tables 会针对 versemind 数据库运行。
• 使用 project: "linecrush" 的 execute 会被拒绝，因为 linecrush 位于 NEON_PG_READONLY_PROJECTS 中。
• list_projects 会显示全部三个名称及其主机和数据库（绝不显示凭据）。

默认项目解析： 名为 default 的项目（来自 NEON_PG_CONNECTION_STRING 或 NEON_PG_CONNECTIONS 中的 default 键）是读取工具的默认项目。如果不存在 default，但恰好配置了一个项目，则该项目为默认项目。如果配置了多个命名项目且没有 default，读取工具必须显式指定 project 参数。

多项目安全规则

这些规则旨在确保读取工具结果或执行写入操作时，始终清楚它访问的是哪个数据库：

1. execute 始终要求提供明确的 project 参数。 写入操作没有默认值，也不会进行推断；缺少项目或项目未知时会报错，列出有效名称，并且不会执行任何操作。
2. 每个工具结果都包含一个 source 块（project、database、host）——无论成功还是出错，无论读取还是写入。错误文本前会加上 [project=... database=...]。
3. NEON_PG_READONLY_PROJECTS 会按项目硬性阻止 execute，即使明确提供了 project 参数也一样。
4. MCP 资源（neon://...）只从默认项目提供。

使用方法

运行服务

选择以下可用实现之一：

ES Module 版本（推荐）：

node pg-mcp-server.js

CommonJS 版本：

node index.js

基础版本：

node basic-pg-server.js

TypeScript 版本：

# First compile
npm run build
# Then run
node build/index.js

与 Claude Desktop 集成

1. 打开 Claude Desktop 设置
2. 前往 Developer → MCP Servers
3. 添加新的服务配置：

{
  "neon-postgres": {
    "command": "node",
    "args": ["/path/to/neon-pg-server/pg-mcp-server.js"],
    "env": {
      "NEON_PG_CONNECTION_STRING": "your-connection-string-here"
    }
  }
}

与 Cursor IDE 集成

1. 打开 File → Preferences → Cursor Settings → MCP
2. 添加新服务
3. 将服务脚本的路径配置为服务路径

可用工具

生产版 pg-mcp-server.js 提供 9 个工具。每个工具都包含适用于 Claude/Codex 的标题、读写注释、结构化输出架构以及 JSON 文本回退。

除 list_projects 外，每个工具都接受可选的 project 参数，用于选择要连接的指定项目（默认：default 项目）。对于 execute，project 参数为必填项。每个结果都包含一个 source 块，注明操作所针对的项目、数据库和主机。

0. 列出项目工具

列出已配置的项目连接：名称、主机、数据库、默认标记和只读标记。绝不返回凭据。

参数： 无

1. 查询工具

执行只读的 SELECT、WITH 和 EXPLAIN 查询，从数据库中检索数据。

查询工具在只读事务中运行，并会将未限制的顶层结果集安全地限制为最多 100 行，因此 Agent 在探索时可以省略 LIMIT。允许使用末尾分号。

参数：

• sql（必填）：要执行的 SQL SELECT、WITH 或 EXPLAIN 语句
• params（可选）：用于参数化查询的查询参数数组

示例：

SELECT * FROM users WHERE age > $1

2. 执行工具

执行会修改数据的 SQL 语句（INSERT、UPDATE、DELETE、DDL）。

参数：

• sql（必填）：要执行的 SQL 语句
• project（必填）：要写入的指定项目——写入操作没有默认值
• params（可选）：语句参数数组

对于 NEON_PG_READONLY_PROJECTS 中列出的项目，将直接拒绝执行。

示例：

INSERT INTO users (name, email) VALUES ($1, $2)

3. 列出慢查询工具

列出 pg_stat_statements 跟踪的最慢语句。

参数：

• limit（可选）：返回的查询数上限，默认为 10，硬性上限为 25
• order_by（可选）：排序指标，可选 mean_exec_time、total_exec_time、calls 或 rows
• min_mean_ms（可选）：平均执行时间的最低值，单位为毫秒

如果未安装 pg_stat_statements，该工具会返回结构化的设置说明，而不是晦涩的数据库错误。

4. 获取表工具

列出 public 架构中的表，并提供近似大小和列数。

参数： 无

5. 获取架构工具

返回架构概览：表名、大小、行数估算、列数和分页元数据。

参数：

• tables（可选）：要包含的指定 public 表
• limit（可选）：返回的表数上限，默认为 50，硬性上限为 200
• offset（可选）：分页时跳过的表数
• include_all（可选）：包含备份/归档表

6. 描述表工具

获取特定公共表的详细结构信息。

参数：

• table（必填）：要描述的表名

返回：

• 列信息（名称、数据类型、是否可为空、默认值）
• 主键列、外键、索引、枚举值、JSONB 键（每列最多从 50 行非空数据中采样）、大小、行数估算

7. 数据采样工具

返回公共表中的几行数据，以及推断出的 JSONB 结构。

参数：

• table（必填）：要采样的表名
• limit（可选）：行数，默认为 3，硬性上限为 10

8. 搜索架构工具

按不区分大小写的文本模式搜索公共表名和列名。

参数：

• pattern（必填）：要在表名和列名中搜索的文本

Agent 使用便利性

• 服务说明会告知 Claude/Codex 如何使用架构发现工具，并避免不必要的 LIMIT 重试。
• 工具注释将只读工具与写入工具区分开来，以便主机更安全地设置权限和确认要求。
• 自动补全会为表名、提示词参数、资源模板参数和采样行数提供建议。
• 结构化日志支持由客户端控制日志级别，同时避免向 stdout 写入会破坏协议的输出。
• 负载预算控制会在 Claude 收到结果前，将过大的查询、采样和慢查询结果裁剪到主机限制以内。
• 慢查询发现为 Agent 提供安全的 pg_stat_statements 入口，以便在开始优化查询前进行探索。

安全注意事项

• 连接字符串：将连接字符串存储为环境变量，切勿提交到版本控制系统
• SSL/TLS：服务会强制通过 SSL 连接到 Neon PostgreSQL
• 来源标注：每个工具结果和错误都会注明其运行所针对的项目、数据库和主机，因此结果绝不会被错误归因到其他数据库
• 写入目标指定：execute 要求显式提供 project 参数，并遵循 NEON_PG_READONLY_PROJECTS 的设置
• 查询验证：服务会验证以下内容：
  • 查询工具只接受 SELECT、WITH 和 EXPLAIN 语句
  • 查询工具在只读事务中运行
  • 无界限的顶层查询结果最多返回 100 行，无需 Agent 编写 LIMIT
  • 执行工具会拒绝 SELECT 语句（请改用查询工具）
• 负载控制：查询和采样结果会通过截断较大的单元格来控制在主机负载限制以内，必要时才会截断行
• 参数化查询：使用参数化查询，防止 SQL 注入

配置

连接池设置

服务使用以下默认连接池设置：

• 最大连接数：10
• 空闲超时：30 秒

可以在连接池初始化代码中修改这些设置：

this.pool = new pg.Pool({
  connectionString: CONNECTION_STRING,
  ssl: { rejectUnauthorized: true },
  max: 10,  // Adjust as needed
  idleTimeoutMillis: 30000  // Adjust as needed
});

开发

项目结构

neon-pg-server/
├── pg-mcp-server.js      # Main ES module implementation
├── index.js              # CommonJS implementation
├── basic-pg-server.js    # Basic implementation
├── src/
│   └── index.ts         # TypeScript implementation
├── build/               # Compiled TypeScript output
├── package.json         # Project dependencies
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

从 TypeScript 构建

如果要使用 TypeScript 版本：

# Install dev dependencies
npm install

# Compile TypeScript
npx tsc

# Run compiled version
node build/index.js

故障排除

连接问题

• 确认连接字符串正确
• 确保 Neon 数据库处于活动状态
• 检查是否已启用 SSL（Neon 要求启用）

MCP 客户端问题

• 确保 MCP 客户端能够找到服务可执行文件
• 检查是否已将环境变量正确传递给服务
• 查看服务日志（输出到 stderr），查找错误消息

查询错误

• 确认 SQL 语法正确
• 检查表和列是否存在
• 确保数据库操作权限正确

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件

致谢

• 基于 Model Context Protocol SDK 构建
• 由 Neon PostgreSQL 提供支持
• 灵感来自 MCP 生态系统和社区