PostgreSQL 完全访问 MCP 服务器

一个强大的模型上下文协议服务器，提供对 PostgreSQL 数据库的完全读写访问。与只读的官方 MCP PostgreSQL 服务器不同，这个增强的实现允许大型语言模型 (LLM) 在适当的事务管理和安全控制下，查询和修改数据库内容。

目录

• 特性
  • 完全读写访问
  • 丰富的模式信息
  • 高级安全控制
• 工具
  • execute_query
  • execute_dml_ddl_dcl_tcl
  • execute_commit
  • execute_rollback
  • list_tables
  • describe_table
• 资源
• 与 Claude Desktop 一起使用
  • Claude Desktop 集成
  • 重要提示：使用“允许一次”以确保安全
• 环境变量
• 使用 Claude 进行完全数据库访问
• 安全注意事项
  • 数据库用户权限
  • 安全使用的最佳实践
• Docker
• 许可证
• 与官方 PostgreSQL MCP 服务器的比较

🌟 特性

完全读写访问

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

丰富的模式信息

• 详细的列元数据（数据类型、描述、最大长度、可空性）
• 主键标识
• 外键关系
• 带有类型和唯一性标志的索引信息
• 表行数估计
• 表和列描述（如果可用）

高级安全控制

• SQL 查询分类（DQL、DML、DDL、DCL、TCL）
• 强制执行只读查询以确保安全
• 所有操作都在隔离的事务中运行
• 自动事务超时监控
• 可配置的安全限制
• 带有显式用户确认的两步事务提交过程

🔧 工具

• execute_query

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

• execute_dml_ddl_dcl_tcl

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

• execute_commit

  • 通过其 ID 显式提交事务
  • 输入：transaction_id (字符串): 要提交的事务的 ID
  • 安全地处理提交或回滚后的清理
  • 将更改永久应用于数据库

• execute_rollback

  • 通过其 ID 显式回滚事务
  • 输入：transaction_id (字符串): 要回滚的事务的 ID
  • 安全地丢弃所有更改并清理资源
  • 在查看更改并决定不应用它们时很有用

• list_tables

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

• describe_table

  • 获取有关特定表结构的详细信息
  • 输入：table_name (字符串): 要描述的表的名称
  • 返回完整的模式信息，包括主键、外键、索引和列详细信息

📊 资源

服务器为数据库表提供增强的模式信息：

• 表模式 (postgres://<host>/<table>/schema)
  • 每个表的详细 JSON 模式信息
  • 包括完整的列元数据、主键和约束
  • 从数据库元数据自动发现

🚀 与 Claude Desktop 一起使用

Claude Desktop 集成

要将此服务器与 Claude Desktop 一起使用，请按照以下步骤操作：

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

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

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

{
  "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 配置中的环境变量自定义服务器行为：

"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：分析您的数据库并创建一个查询

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 并结束对话
   • 您查看结果
   • 在新的对话中，您回复“Yes”以提交或“No”以回滚
   • Claude Desktop 向您准确显示将要更改的内容并请求权限
   • 您单击“允许一次”以允许特定操作
   • Claude 执行该操作并返回结果

这使您有多次机会在将更改永久应用于数据库之前验证更改。

⚠️ 安全注意事项

使用写入权限将 Claude 连接到您的数据库时：

数据库用户权限

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

-- 创建受限用户的示例（根据需要进行调整）
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 容器中运行：

# 构建 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 连接到主机网络：

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)

---

版权所有 © 2024 Syahiid Nur Kamil。保留所有权利。