pg-mcp-server
If you are the rightful owner of pg-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
PostgreSQL MCP Server allows AI assistants to securely perform database operations using the Model Context Protocol.
作者微信：1875954969
PostgreSQL MCP 服务器
基于Model Context Protocol (MCP)的PostgreSQL数据库访问服务器。该服务器允许AI助手安全地执行PostgreSQL数据库操作，包括查询、插入、更新和删除数据，以及表结构操作。
目录结构
pg-mcp-server/
├── dist/ # 编译后的JavaScript文件
├── src/ # 源代码目录
│ └── lib/ # 核心库文件
│ ├── config.ts # 配置参数定义
│ ├── index.ts # 主入口文件和服务器初始化
│ ├── tool-handlers.ts # 处理各种数据库操作的函数
│ ├── transaction-manager.ts # 事务管理器
│ ├── types.ts # 类型定义
│ └── utils.ts # 工具函数
├── package.json # 项目依赖定义
├── tsconfig.json # TypeScript编译配置
└── README.md # 项目说明文档
核心脚本说明
src/lib 目录下的脚本
-
index.ts
- 作用：主入口文件，用于初始化和启动MCP服务器。
- 功能：注册数据库操作工具，设置PostgreSQL连接池，初始化事务管理器，处理命令行参数。
- 特点：使用MCP SDK创建服务器，注册各种工具函数以处理数据库操作请求。
-
tool-handlers.ts
- 作用：包含所有数据库操作的处理函数。
- 功能：实现SQL查询执行、数据修改操作、表列表获取、表结构描述等功能。
- 处理函数：
handleExecuteQuery: 处理只读SQL查询handleExecuteDML: 处理数据修改操作(INSERT, UPDATE, DELETE等)handleExecuteCommit: 提交事务handleExecuteRollback: 回滚事务handleListTables: 列出数据库中的所有表handleDescribeTable: 获取表结构详细信息
-
transaction-manager.ts
- 作用：管理数据库事务的生命周期。
- 功能：跟踪活动事务，处理事务超时，确保资源正确释放。
- 关键方法：添加、删除、提交和回滚事务，以及监控事务超时。
-
types.ts
- 作用：定义项目中使用的类型和常量。
- 内容：
TrackedTransaction接口用于跟踪事务状态，以及其他常量定义。
-
utils.ts
- 作用：提供通用工具函数。
- 功能：
safelyReleaseClient: 安全释放PostgreSQL客户端连接generateTransactionId: 生成唯一事务IDisReadOnlyQuery: 检查SQL是否为只读查询
-
config.ts
- 作用：定义服务器配置项。
- 内容：事务超时设置、监控间隔、PostgreSQL连接池参数等。
- 特点：支持通过环境变量覆盖默认配置。
MCP SDK 的使用
该项目使用Model Context Protocol (MCP) SDK来实现与AI助手的标准化通信：
-
服务器创建：
const server = new McpServer( { name: "postgres-full-access", version: "0.1.0", }, { capabilities: { resources: {}, tools: {}, }, } ); -
工具注册：
server.tool( "execute_query", "运行只读 SQL 查询（SELECT 语句）", { sql: z.string().describe("要执行的 SQL 查询") }, async (args, extra) => { // 处理查询 } ); -
连接和启动：
const transport = new StdioServerTransport(); await server.connect(transport);
安装和运行步骤
前置条件
- Node.js 18.x 或更高版本
- PostgreSQL 数据库实例
- npm 或 yarn 包管理器
安装步骤
-
克隆仓库
git clone https://github.com/cynhardchueng/pg-mcp-server.git cd pg-mcp-server -
安装依赖
npm install如果需要单独安装或更新MCP SDK，请使用：
npm install @modelcontextprotocol/sdk@1.8.0 -
编译TypeScript代码
npm run build -
配置Cursor的MCP配置
在Cursor编辑器中，需要配置mcp.json文件。一般位于
~/.cursor/mcp.json，添加以下内容："pg-mcp-server": { "command": "node", "args": [ "项目路径/dist/index.js", "postgresql://用户名:密码@数据库地址:端口/数据库名" ], "env": { "TRANSACTION_TIMEOUT_MS": "60000", "MAX_CONCURRENT_TRANSACTIONS": "5", "PG_STATEMENT_TIMEOUT_MS": "30000" } }注意：请将上述配置中的"项目路径"、"用户名"、"密码"、"数据库地址"、"端口"和"数据库名"替换为实际值。
运行服务器
-
基本运行命令
node dist/index.js postgresql://用户名:密码@数据库地址:端口/数据库名 -
使用环境变量配置
TRANSACTION_TIMEOUT_MS=30000 PG_MAX_CONNECTIONS=30 node dist/index.js postgresql://用户名:密码@数据库地址:端口/数据库名
可用的环境变量
| 环境变量 | 描述 | 默认值 |
|---|---|---|
| TRANSACTION_TIMEOUT_MS | 事务超时时间(毫秒) | 15000 |
| MONITOR_INTERVAL_MS | 监控间隔时间(毫秒) | 5000 |
| ENABLE_TRANSACTION_MONITOR | 启用事务监控 | true |
| MAX_CONCURRENT_TRANSACTIONS | 最大并发事务数 | 10 |
| PG_MAX_CONNECTIONS | 连接池最大连接数 | 20 |
| PG_IDLE_TIMEOUT_MS | 空闲连接超时(毫秒) | 30000 |
| PG_STATEMENT_TIMEOUT_MS | SQL语句执行超时(毫秒) | 30000 |
示例使用
通过MCP协议，AI助手可以执行以下类型的操作:
-
执行只读查询
SELECT * FROM users WHERE age > 18; -
执行数据修改
INSERT INTO users (name, age) VALUES ('张三', 25);重要：执行数据修改操作(INSERT、UPDATE、DELETE等)后，需要在对话中明确回复"yes"（确认提交）或"no"（回滚事务）。例如：
AI: 已执行插入操作，事务ID: tx_12345。请回复"yes"提交事务，或"no"回滚事务。 用户: yes AI: 事务已成功提交，数据已永久保存。 -
查看表结构
获取表"users"的详细信息 -
列出所有表
列出数据库中的所有表
注意事项
- 确保数据库用户具有适当的权限来执行所需的操作。
- 对于生产环境，建议配置更严格的超时设置和连接池参数。
- 事务会在超时后自动回滚，以防止长时间运行的事务占用资源。
- 数据修改操作：所有DML操作(INSERT、UPDATE、DELETE)都在事务中执行，必须显式提交才会永久保存。如果用户没有回复"yes"确认提交，或会话结束，事务将自动回滚。
- 请勿在配置文件中使用生产环境的数据库凭据，尤其是在公开分享代码时。
- 尽量只使用查询分析功能，不要直接对生产库进行增删改，属于高危操作，请慎重
