Postgresql MCP

postgresql-mcp

一个适用于 PostgreSQL 的模型上下文协议（MCP）服务，提供完整的读写支持、原子事务和架构检查。可与 Claude Desktop、Cursor、Windsurf 及任何兼容 MCP 的 AI 客户端配合使用。

只需数秒，即可将任意 PostgreSQL 数据库——本地、Supabase、AWS RDS 或可自托管的数据库——连接到你的 AI 助手。

功能

• 完整的 SQL 读写访问权限（SELECT、INSERT、UPDATE、DELETE、CREATE、DROP）
• 支持多个 SQL 语句的原子事务；失败时自动回滚
• 架构检查：列、类型、可空性、默认值、主键
• 可通过 ?mode=readonly 启用只读模式
• 不受云平台锁定——适用于任何标准 PostgreSQL 连接字符串
• 单文件，依赖项精简

为什么要开发它

还有两个值得了解的 PostgreSQL MCP 服务，但它们都无法完全满足通用场景的需求：

Anthropic 官方的 @modelcontextprotocol/server-postgres 严格限制为只读——它只提供一个在 READ ONLY 事务中运行的 query 工具。不支持写入、DDL 或事务。此外，该项目已于 2025 年 7 月弃用并归档。

Microsoft 的 azure-postgresql-mcp 支持写入和 DDL，但专为 Azure Database for PostgreSQL Flexible Server 构建。虽然它在技术上接受标准 PG* 环境变量（因此本地连接可能可用），但本地使用未经测试且不受支持。多个工具需要 Microsoft Entra 身份验证和 Azure 专属 API，在 Azure 之外无法运行。它还引入了非 Azure 环境不需要的 Azure SDK 依赖项。目前该项目处于预览版。

此服务是其他所有场景的替代方案：本地 PostgreSQL、可自托管的数据库、Supabase、RDS 或任何标准 PostgreSQL 实例。它是一个依赖精简的单文件服务，不受云平台锁定，提供完整的读写支持和多个 SQL 语句的原子事务；需要限制访问时，还可使用可选的 ?mode=readonly 标志。

要求

• Node.js 18+
• 正在运行的 PostgreSQL 数据库

安装

npm install -g @sarmadparvez/postgresql-mcp

也可以直接运行而无需安装（需要 npm 7+ / Node.js 18+）：

npx @sarmadparvez/postgresql-mcp <postgresql-connection-string>

用法

postgresql-mcp <postgresql-connection-string>

示例：

# Read-write access
postgresql-mcp postgresql://user:pass@localhost:5432/mydb

# Read-only mode (disables execute and transaction tools)
postgresql-mcp postgresql://user:pass@localhost:5432/mydb?mode=readonly

也可以通过 npx 运行（需要 npm 7+ / Node.js 18+）：

npx @sarmadparvez/postgresql-mcp postgresql://user:pass@localhost:5432/mydb
npx @sarmadparvez/postgresql-mcp postgresql://user:pass@localhost:5432/mydb?mode=readonly

工具

工具	可用模式	描述
query	始终可用	执行只读的 SELECT 查询。在 READ ONLY 事务中运行。以 JSON 格式返回行。
execute	读写模式	执行写入 SQL 语句（INSERT、UPDATE、DELETE、CREATE、DROP 等）。返回受影响的行数。
schema	始终可用	列出指定架构中表的列、类型、可空性、默认值和主键。可选按特定表筛选。
list_tables	始终可用	列出架构中的所有基本表及其磁盘大小。
transaction	读写模式	以原子方式执行多个 SQL 语句。任何一条语句失败时，都会回滚所有语句。

只读模式

在连接字符串后添加 ?mode=readonly，即可在只读模式下启动服务。此模式会禁用 execute 和 transaction 工具，仅保留 query、schema 和 list_tables。

Claude Desktop 配置

首先，全局安装该软件包：

npm install -g @sarmadparvez/postgresql-mcp

然后，查找 node 和已安装脚本的路径：

which node
# e.g. /usr/local/bin/node
# nvm users: /Users/yourname/.nvm/versions/node/v22.12.0/bin/node

npm root -g
# e.g. /usr/local/lib/node_modules
# nvm users: /Users/yourname/.nvm/versions/node/v22.12.0/lib/node_modules

将以下内容添加到你的 claude_desktop_config.json：

• 将 command 替换为 which node 的输出
• 将脚本路径的前缀替换为 npm root -g 的输出；后缀 /@sarmadparvez/postgresql-mcp/index.js 保持不变

{
  "mcpServers": {
    "postgres": {
      "command": "/usr/local/bin/node",
      "args": [
        "/usr/local/lib/node_modules/@sarmadparvez/postgresql-mcp/index.js",
        "postgresql://user:pass@localhost:5432/mydb"
      ]
    }
  }
}

如需只读访问权限，请在连接字符串后追加 ?mode=readonly：

{
  "mcpServers": {
    "postgres-readonly": {
      "command": "/usr/local/bin/node",
      "args": [
        "/usr/local/lib/node_modules/@sarmadparvez/postgresql-mcp/index.js",
        "postgresql://user:pass@localhost:5432/mydb?mode=readonly"
      ]
    }
  }
}

兼容的 AI 客户端

此 MCP 服务适用于任何支持 Model Context Protocol 的客户端：

• Claude Desktop（Anthropic）
• Cursor
• Windsurf
• 任何其他兼容 MCP 的客户端

依赖项

• @modelcontextprotocol/sdk — MCP 服务框架
• pg — PostgreSQL 客户端
• zod — 工具输入的架构验证