内容
# PostgreSQL 全面访问 MCP 服务器
[](https://modelcontextprotocol.io)
[](LICENSE)
一个强大的模型上下文协议服务器，提供对 PostgreSQL 数据库的**完全读写访问**。与官方的只读 MCP PostgreSQL 服务器不同，该增强实现允许大型语言模型（LLM）查询和修改数据库内容，具有适当的事务管理和安全控制。
## 目录
- [功能](#功能)
- [完全读写访问](#完全读写访问)
- [丰富的模式信息](#丰富的模式信息)
- [高级安全控制](#高级安全控制)
- [工具](#工具)
- [执行查询](#execute_query)
- [执行 DML、DDL、DCL 和 TCL](#execute_dml_ddl_dcl_tcl)
- [执行维护](#execute_maintenance)
- [提交事务](#execute_commit)
- [回滚事务](#execute_rollback)
- [列出表格](#list_tables)
- [描述表格](#describe_table)
- [资源](#资源)
- [与 Claude Desktop 结合使用](#使用claude-desktop)
- [Claude Desktop 集成](#claude-desktop-集成)
- [重要：使用“允许一次”进行安全保护](#重要：使用allow-once进行安全保护)
- [环境变量](#环境变量)
- [与 Claude 结合使用全数据库访问](#使用全数据库访问与claude)
- [安全考虑](#安全考虑)
- [数据库用户权限](#数据库用户权限)
- [安全使用的最佳实践](#安全使用的最佳实践)
- [Docker](#docker)
- [许可证](#许可证)
- [与官方 PostgreSQL MCP 服务器比较](#与官方postgresql-mcp服务器比较)
## 🌟 功能
### 完全读写访问
- 安全执行 DML 操作（INSERT、UPDATE、DELETE）
- 使用 DDL 创建、修改和管理数据库对象
- 具有显式提交的事务管理
- 安全超时和自动回滚保护
### 丰富的模式信息
- 详细的列元数据（数据类型、描述、最大长度、是否可为空）
- 主键识别
- 外键关系
- 具有类型和唯一性标志的索引信息
- 表行数估计
- 表和列描述（如果可用）
### 高级安全控制
- SQL 查询分类（DQL、DML、DDL、DCL、TCL）
- 强制执行只读操作以确保安全查询
- 所有操作都在隔离的事务中运行
- 自动事务超时监控
- 可配置的安全限制
- 具有显式用户确认的两步事务提交过程
## 🔧 工具
- **执行查询**
- 执行只读 SQL 查询（SELECT 语句）
- 输入：`sql`（字符串）：要执行的 SQL 查询
- 所有查询都在只读事务中执行
- 结果包括执行时间指标和字段信息
- **执行 DML、DDL、DCL 和 TCL**
- 执行数据修改操作（INSERT、UPDATE、DELETE）或模式更改（CREATE、ALTER、DROP）
- 输入：`sql`（字符串）：要执行的 SQL 语句
- 自动在具有可配置超时的事务中包装
- 返回事务 ID 以进行显式提交
- **重要安全功能**：对话将在执行后结束，允许用户在决定提交或回滚之前查看结果
- **执行维护**
- 执行维护命令，如 VACUUM、ANALYZE 或 CREATE DATABASE 以外事务
- 输入：`sql`（字符串）：要执行的 SQL 语句 - 必须是 VACUUM、ANALYZE 或 CREATE DATABASE
- 返回具有执行时间指标的结果对象
- **提交事务**
- 通过其 ID 显式提交事务
- 输入：`transaction_id`（字符串）：要提交的事务 ID
- 安全地处理提交或回滚后的清理
- 永久将更改应用于数据库
- **回滚事务**
- 通过其 ID 显式回滚事务
- 输入：`transaction_id`（字符串）：要回滚的事务 ID
- 安全地丢弃所有更改并清理资源
- 在查看更改并决定不应用它们时非常有用
- **列出表格**
- 获取数据库中所有表格的综合列表
- 包括列数和表格描述
- 无输入参数要求
- **描述表格**
- 获取特定表格结构的详细信息
- 输入：`table_name`（字符串）：要描述的表格名称
- 返回完整的模式信息，包括主键、外键、索引和列详细信息
## 📊 资源
服务器提供增强的模式信息用于数据库表格：
- **表格模式** (`postgres://<host>/<table>/schema`)
- 每个表格的详细 JSON 模式信息
- 包括完整的列元数据、主键和约束
- 自动从数据库元数据中发现
## 🚀 与 Claude Desktop 结合使用
### Claude Desktop 集成
要将此服务器与 Claude Desktop 结合使用，请按照以下步骤：
1. 首先，确保您的系统上已安装 Node.js
2. 使用 npx 安装软件包或将其添加到您的项目中
3. 通过编辑 `claude_desktop_config.json`（通常位于 `~/Library/Application Support/Claude/`）配置 Claude Desktop：
```json
{
"mcpServers": {
"postgres-full": {
"command": "npx",
"args": [
"-y",
"mcp-postgres-full-access",
"postgresql://username:password@localhost:5432/database"
],
"env": {
"TRANSACTION_TIMEOUT_MS": "60000",
"MAX_CONCURRENT_TRANSACTIONS": "5",
"PG_STATEMENT_TIMEOUT_MS": "30000"
}
}
}
}
```
4. 将数据库连接字符串替换为实际的 PostgreSQL 连接详细信息
5. 完全重启 Claude Desktop
### 重要：使用“允许一次”进行安全保护
当 Claude 尝试将更改提交到您的数据库时，Claude Desktop 将提示您批准：
**始终仔细审查 SQL 更改后再批准！**
安全最佳实践：
- 始终点击“允许一次”（而非“始终允许”）进行提交操作
- 仔细审查事务 SQL 后再批准
- 考虑使用具有有限权限的数据库用户
- 可能时使用测试数据库
此“允许一次”方法让您完全控制，防止对数据库进行不想要的更改，同时允许 Claude 在需要时帮助进行数据管理任务。
## ⚙️ 环境变量
您可以使用 Claude Desktop 配置中的环境变量自定义服务器行为：
```json
"env": {
"TRANSACTION_TIMEOUT_MS": "60000",
"MAX_CONCURRENT_TRANSACTIONS": "5"
}
```
关键环境变量：
- `TRANSACTION_TIMEOUT_MS`：事务超时（毫秒）（默认值：15000）
- 增加此值以适应需要更多时间的事务
- 超出此时间的事务将自动回滚以确保安全
- `MAX_CONCURRENT_TRANSACTIONS`：最大并发事务数（默认值：10）
- 降低此值以实现更保守的操作
- 更高的值允许更多的并发写操作
- `ENABLE_TRANSACTION_MONITOR`：启用/禁用事务监视器（“true”或“false”，默认值：“true”）
- 监视并自动回滚被遗弃的事务
- 很少需要禁用
- `PG_STATEMENT_TIMEOUT_MS`：SQL 查询执行超时（毫秒）（默认值：30000）
- 限制单个 SQL 语句的运行时间
- 重要的安全功能，防止失控的查询
- `PG_MAX_CONNECTIONS`：最大 PostgreSQL 连接数（默认值：20）
- 重要的保持在数据库的连接限制内
- `MONITOR_INTERVAL_MS`：多久检查一次卡住的事务（默认值：5000）
- 通常不需要调整
## 🔄 与 Claude 结合使用全数据库访问
此服务器使 Claude 能够读写您的 PostgreSQL 数据库，并在您批准的情况下。以下是一些示例对话流程：
### 示例：创建新表格和添加数据
您： “我需要一个包含 id、name、price 和 inventory 列的新 products 表”
Claude： _分析您的数据库并创建查询_
```sql
CREATE TABLE products (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
price DECIMAL(10,2) NOT NULL,
inventory INTEGER DEFAULT 0
);
```
_Claude Desktop 将提示您批准此操作_
您： _审查并点击“允许一次”_
Claude： “我已创建 products 表。您是否要添加一些示例数据？”
您： “是的，请添加 5 个示例产品”
Claude： _创建 INSERT 语句并提示批准_
_您审查并批准，点击“允许一次”_
### 示例：使用安全查询进行数据分析
您： “我的前 3 个产品按价格排序是什么？”
Claude： _自动执行只读查询_
_显示结果_
### 安全工作流程
任何修改数据库的操作的关键安全功能是两步法：
1. Claude 分析您的请求并准备 SQL
2. 对于只读操作（SELECT），Claude 自动执行
3. 对于写操作（INSERT、UPDATE、DELETE、CREATE 等）：
- Claude 在事务中执行 SQL 并结束对话
- 您审查结果
- 在新对话中，您用“是”提交或用“否”回滚
- Claude Desktop 显示将更改的内容并请求许可
- 您点击“允许一次”以允许特定操作
- Claude 执行操作并返回结果
这样，您有多个机会在更改永久应用于数据库之前验证更改。
## ⚠️ 安全考虑
连接 Claude 到具有写访问权限的数据库时：
### 数据库用户权限
**重要：** 创建具有适当权限的专用数据库用户：
```sql
-- 创建受限用户的示例（根据需要调整）
CREATE USER claude_user WITH PASSWORD 'secure_password';
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_user;
GRANT INSERT, UPDATE, DELETE ON TABLE table1, table2 TO claude_user;
-- 仅授予必要的权限
```
### 安全使用的最佳实践
1. **始终使用“允许一次”** 审查每个写操作
- 绝不为数据库修改选择“始终允许”
- 花时间仔细审查 SQL
2. **连接到测试数据库** 在首次探索此工具时
- 考虑使用数据库副本/备份进行初始测试
3. **限制数据库用户权限** 仅限必要权限
- 避免使用超级用户或管理员帐户
- 可能时授予特定表格的权限
4. **在广泛使用前实施数据库备份**
5. **绝不共享不应暴露给 LLM 的敏感数据**
6. **在批准前验证所有 SQL 操作**
- 检查表格名称
- 验证列名和数据
- 确认 WHERE 子句适当
- 查看正确的事务处理
### Docker
可以在 Docker 容器中轻松运行服务器：
```bash
# 构建 Docker 镜像
docker build -t mcp-postgres-full-access .
# 运行容器
docker run -i --rm mcp-postgres-full-access "postgresql://username:password@host:5432/database"
```
对于 macOS 上的 Docker，请使用 host.docker.internal 连接到主机网络：
```bash
docker run -i --rm mcp-postgres-full-access "postgresql://username:password@host.docker.internal:5432/database"
```
## 📄 许可证
此 MCP 服务器根据 MIT 许可证授权。
## 💡 与官方 PostgreSQL MCP 服务器比较
| 功能 | 此服务器 | 官方 MCP PostgreSQL 服务器 |
| ------------------- | ---------------------- | ------------------------------ |
| 读取访问 | ✅ | ✅ |
| 写访问 | ✅ | ❌ |
| 模式详情 | 增强 | 基础 |
| 事务支持 | 显式超时 | 只读 |
| 索引信息 | ✅ | ❌ |
| 外键详情 | ✅ | ❌ |
| 行数估算 | ✅ | ❌ |
| 表格描述 | ✅ | ❌ |
## 作者
由 Syahiid Nur Kamil ([@syahiidkamil](https://github.com/syahiidkamil)) 创建
---
版权 © 2024 Syahiid Nur Kamil。保留所有权利。
