PostgreSQL Full Access MCP Server

PostgreSQL 完全访问 MCP 服务

本项目是由 Syahiid Kamil 创建的原始 mcp-postgres-full-access 项目的独立维护增强版分支。

这是一个功能强大的 Model Context Protocol 服务，可提供对 PostgreSQL 数据库的完整读写访问。与官方的只读 MCP PostgreSQL 服务不同，这个增强版实现允许大模型在具备适当事务管理和安全控制的情况下查询和修改数据库内容。

目录

• 功能
  • 完整读写访问
  • 丰富的架构信息
  • 高级安全控制
• 工具
  • execute_query
  • execute_dml_ddl_dcl_tcl
  • execute_maintenance
  • execute_commit
  • execute_rollback
  • list_tables
  • describe_table
  • list_schemas
• 资源
• 与 Claude Desktop 搭配使用
  • Claude Desktop 集成
  • 重要提示：使用“Allow Once”确保安全
• 环境变量
• 使用 Claude 完全访问数据库
• 安全注意事项
  • 数据库用户权限
  • 安全使用最佳实践
• Docker
• 许可证
• 与官方 PostgreSQL MCP 服务的比较

🌟 功能

完整读写访问

• 安全执行 DML 操作（INSERT、UPDATE、DELETE）
• 使用 DDL 创建、更改和管理数据库对象
• 通过显式提交管理事务
• 安全超时和自动回滚保护

丰富的架构信息

• 详细的列元数据（数据类型、说明、最大长度、是否可为空）
• 主键识别
• 外键关系
• 索引信息，包含类型和唯一性标记
• 表行数估算
• 表和列说明（如果可用）

高级安全控制

• SQL 查询分类（DQL、DML、DDL、DCL、TCL）
• 对安全查询强制实施只读执行
• 所有操作均在隔离事务中运行
• 自动监控事务超时
• 可配置的安全限制
• 两步事务提交流程，需用户明确确认

🔧 工具

• execute_query

  • 执行只读 SQL 查询（SELECT 语句）
  • 输入：sql（字符串）：要执行的 SQL 查询
  • 所有查询都在只读事务中执行
  • 结果包含执行时间指标和字段信息

• execute_dml_ddl_dcl_tcl

  • 执行数据修改操作（INSERT、UPDATE、DELETE）或架构变更（CREATE、ALTER、DROP）
  • 输入：sql（字符串）：要执行的 SQL 语句
  • 自动包装在具有可配置超时的事务中
  • 返回事务 ID，供显式提交使用
  • 重要安全功能：执行后对话将结束，让用户在决定提交或回滚之前查看结果

• execute_maintenance

  • 在事务外执行 VACUUM、ANALYZE 或 CREATE DATABASE 等维护命令
  • 输入：sql（字符串）：要执行的 SQL 语句——必须是 VACUUM、ANALYZE 或 CREATE DATABASE
  • 返回包含执行时间指标的结果对象

• execute_commit

  • 根据事务 ID 显式提交事务
  • 输入：transaction_id（字符串）：要提交的事务 ID
  • 在提交或回滚后安全地处理清理工作
  • 将更改永久应用到数据库

• execute_rollback

  • 根据事务 ID 显式回滚事务
  • 输入：transaction_id（字符串）：要回滚的事务 ID
  • 安全地丢弃所有更改并清理资源
  • 适用于检查更改后决定不应用这些更改的情况

• list_tables

  • 获取数据库中所有表的完整列表
  • 包含列数和表描述
  • 无需输入参数

• describe_table

  • 获取特定表结构的详细信息
  • 输入：table_name（字符串）：要描述的表名
  • 返回完整的架构信息，包括主键、外键、索引和列详情

• list_schemas

  • 获取数据库中所有架构的列表
  • 无需输入参数
  • 返回包含架构名称、所有者和表数量的数组

📊 资源

该服务提供数据库表的增强架构信息：

• 表架构（postgres://<host>/<table>/schema）
  • 每个表的详细 JSON 架构信息
  • 包含完整的列元数据、主键和约束
  • 根据数据库元数据自动发现

🚀 与 Claude Desktop 配合使用

Claude Desktop 集成

要在 Claude Desktop 中使用此服务，请按以下步骤操作：

1. 首先，确保系统已安装 Node.js

2. 使用 npx 安装软件包，或将其添加到项目中

3. 编辑 claude_desktop_config.json 来配置 Claude Desktop（在 macOS 上通常位于 ~/Library/Application Support/Claude/）：

{
  "mcpServers": {
    "postgres-full": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-postgres-full-access-extended",
        "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 配置中通过环境变量自定义服务行为：

"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 列"

Claude：分析你的数据库并创建查询

CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    inventory INTEGER DEFAULT 0
);

Claude Desktop 将提示你批准此操作

你：查看并点击 "Allow once"

Claude："我已创建 products 表。需要我添加一些示例数据吗？"

你："是的，请添加 5 个示例产品"

Claude：创建 INSERT 语句并提示批准 你查看并使用 "Allow once" 批准

示例：使用安全查询进行数据分析

你："我的产品中价格最高的 3 个是什么？"

Claude：自动执行只读查询 向你显示结果

安全工作流

关键安全功能是对任何修改数据库的操作采用两步式方法：

1. Claude 分析你的请求并准备 SQL
2. 对于只读操作（SELECT），Claude 会自动执行
3. 对于写入操作（INSERT、UPDATE、DELETE、CREATE 等）：
   • Claude 在事务中执行 SQL 并结束对话
   • 你查看结果
   • 在新对话中，你回复 "Yes" 以提交，或回复 "No" 以回滚
   • Claude Desktop 会准确显示将要更改的内容并请求许可
   • 你点击 "Allow once" 以允许该特定操作
   • Claude 执行该操作并返回结果

这让你在更改永久应用到数据库之前有多次机会进行核实。

⚠️ 安全注意事项

在让 Claude 以写入权限连接到你的数据库时：

数据库用户权限

重要： 创建一个具有适当权限的专用数据库用户：

-- Example of creating a restricted user (adjust as needed)
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;
-- Only grant specific permissions as needed

安全使用的最佳实践

1. 始终使用 "Allow once" 来查看每次写入操作

   • 切勿为数据库修改选择 "Always allow"
   • 花时间仔细查看 SQL

2. 首次探索此工具时连接到测试数据库

   • 考虑使用数据库副本/备份进行初步测试

3. 限制数据库用户权限，仅授予必要权限

   • 避免使用超级用户或管理员账户
   • 尽可能授予表级权限

4. 在大量使用前实施数据库备份

5. 切勿分享不应暴露给大模型的敏感数据

6. 在批准前核实所有 SQL 操作

   • 检查表名
   • 核实列名和数据
   • 确认 WHERE 子句是否合适
   • 查看事务处理是否正确

Docker

该服务可以轻松地在 Docker 容器中运行：

# Build the Docker image
docker build -t mcp-postgres-full-access .

# Run the container
docker run -i --rm mcp-postgres-full-access "postgresql://username:password@host:5432/database"

在 macOS 上使用 Docker 时，请使用 host.docker.internal 连接到主机网络：

docker run -i --rm mcp-postgres-full-access "postgresql://username:[email protected]:5432/database"

📄 许可证

此 MCP 服务采用 MIT 许可证。

💡 与官方 PostgreSQL MCP 服务的比较

功能	此服务	官方 MCP PostgreSQL 服务
读取权限	✅	✅
写入权限	✅	❌
架构详情	增强	基础
事务支持	显式支持并设有超时	只读
索引信息	✅	❌
外键详情	✅	❌
行数估算	✅	❌
表说明	✅	❌

作者

由 Syahiid Nur Kamil (@syahiidkamil) 创建

由 kamusis (@kamusis) 扩展

---

版权所有 © 2025 kamusis。保留所有权利。