mcp-postgres-advanced

# PostgreSQL 全面访问 MCP 服务器 [](https://modelcontextprotocol.io) [](LICENSE) 一个强大的模型上下文协议服务器，提供对 PostgreSQL 数据库的**完全读写访问**。与仅限读写的官方 MCP PostgreSQL 服务器不同，该增强实现允许大型语言模型（LLM）查询和修改数据库内容，具有适当的事务管理和安全控制。 ## 目录 - [功能](#功能) - [完全读写访问](#完全读写访问) - [丰富的模式信息](#丰富的模式信息) - [高级安全控制](#高级安全控制) - [工具](#工具) - [执行查询](#执行查询) - [执行 DML、DDL、DCL 和 TCL](#执行-dmlddl-dcl-tcl) - [执行维护](#执行维护) - [提交事务](#提交事务) - [回滚事务](#回滚事务) - [列出表格](#列出表格) - [描述表格](#描述表格) - [资源](#资源) - [与 Claude Desktop 结合使用](#与-claude-desktop-结合使用) - [Claude Desktop 集成](#claude-desktop-集成) - [重要：使用“允许一次”进行安全保护](#重要：使用允许一次进行安全保护) - [环境变量](#环境变量) - [与 Claude 结合使用全数据库访问](#与-claude-结合使用全数据库访问) - [安全考虑](#安全考虑) - [数据库用户权限](#数据库用户权限) - [安全使用的最佳实践](#安全使用的最佳实践) - [Docker](#docker) - [许可证](#许可证) - [与官方 PostgreSQL MCP 服务器比较](#与官方-postgresql-mcp-服务器比较) ## 🌟 功能 ### 完全读写访问 - 安全执行 DML 操作（INSERT、UPDATE、DELETE） - 使用 DDL 创建、修改和管理数据库对象 - 具有显式提交的事务管理 - 安全超时和自动回滚保护 ### 丰富的模式信息 - 详细的列元数据（数据类型、描述、最大长度、可空性） - 主键识别 - 外键关系 - 具有类型和唯一性标志的索引信息 - 表行数估计 - 表和列描述（当可用时） ### 高级安全控制 - SQL 查询分类（DQL、DML、DDL、DCL、TCL） - 强制执行安全查询的只读执行 - 所有操作都在隔离的事务中运行 - 自动事务超时监控 - 可配置的安全限制 - 具有显式用户确认的两步事务提交过程 ## 🔧 工具 - **执行查询** - 执行只读 SQL 查询（SELECT 语句） - 输入：`sql`（字符串）：要执行的 SQL 查询 - 所有查询都在 READ ONLY 事务中执行 - 结果包括执行时间指标和字段信息 - **执行 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。保留所有权利。