Postgres Connector MCP

🚀 PostgreSQL MCP Server

PostgreSQL MCP Server 是一个用于查询 PostgreSQL 数据库的 MCP（模型上下文协议）服务器。通过与 MCP 兼容的客户端，你可以执行 SQL 查询、查看表细节并管理数据库连接。

🚀 快速开始

你可以按照以下步骤进行安装并使用 PostgreSQL MCP Server。

✨ 主要特性

• 数据库连接：通过身份验证连接到 PostgreSQL 数据库。
• SQL 执行：执行经过安全验证的 SELECT 查询。
• 连接测试：测试数据库连接状态。

📦 安装指南

Claude Desktop 端安装步骤

步骤 1：下载 MCP 服务器文件

从本仓库（根目录）下载 postgres-connector.mcpb 文件。

步骤 2：安装 MCP 服务器

1. 打开 Claude Desktop。
2. 导航至 设置 > 功能。
3. 点击 “安装扩展” 并选择 postgres-connector.mcpb 文件。

截图占位：安装 .mcpb 文件

步骤 3：配置数据库连接

安装完成后，PostgreSQL 连接器将出现在你的 Claude Desktop 中，带有默认环境变量，你可以使用数据库详细信息进行配置。

截图占位：显示环境变量的数据库配置界面

步骤 4：测试数据库连接

发送查询 “test the database connection”。

📚 详细文档

配置所需的数据库设置

你需要为你的 PostgreSQL 数据库提供以下信息：

在 Claude Desktop 中安装扩展后，这些环境变量将自动在扩展设置面板中可供配置。

可用工具

1. 测试 PostgreSQL 连接

工具：test-postgres-connection 此工具用于测试数据库连接并显示当前配置（为安全起见，密码会隐藏）。

示例输出：

✅ 数据库连接成功！

配置信息：
{
  "host": "localhost",
  "port": "5432",
  "database": "myapp_production",
  "username": "postgres",
  "password": "***hidden***"
}

连接测试结果：[
  {
    "test": 1
  }
]

2. 获取所有表

工具：get-all-tables 该工具用于检索数据库公共模式中的所有表的列表。

示例输出：

[
  {
    "table_name": "users"
  },
  {
    "table_name": "orders"
  },
  {
    "table_name": "products"
  },
  {
    "table_name": "categories"
  }
]

3. 执行 SQL 查询

工具：execute-sql-query 此工具用于在数据库上执行经过安全验证的 SELECT 查询。

输入：

• sql：要执行的 SQL 查询（仅支持 SELECT 语句）

示例用法：

SELECT id, name, email FROM users LIMIT 5;

示例输出：

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
]

安全与保障

SQL 查询验证

PostgreSQL MCP 服务器包含以下安全措施：

• 只读操作：仅允许执行 SELECT 语句。
• 危险关键字拦截：自动阻止 DROP、DELETE、TRUNCATE、ALTER、CREATE、INSERT、UPDATE 操作。
• 语句级验证：对每个 SQL 语句进行单独验证。
• 安全错误处理：捕获并安全显示数据库错误。

最佳实践是为 postgres 连接器创建一个只读数据库用户。

禁止的操作

出于安全考虑，以下 SQL 操作 不被允许：

• DROP（删除表/数据库）
• DELETE（删除数据）
• TRUNCATE（清空表）
• ALTER（修改结构）
• CREATE（创建新对象）
• INSERT（添加数据）
• UPDATE（修改数据）

故障排除

连接问题

问题：“数据库连接失败”

• 检查：验证主机、端口、数据库名称、用户名和密码。
• 检查：确保你的 PostgreSQL 服务器正在运行且可访问。
• 检查：验证你的数据库用户是否具有必要的权限。

问题：“连接超时”

• 检查：你的数据库服务器可能位于防火墙后面。
• 检查：主机地址和端口号是否正确。
• 检查：与数据库服务器的网络连接是否正常。

查询问题

问题：“检测到危险操作”

• 原因：你试图执行非 SELECT 语句。
• 解决方案：出于安全原因，仅允许执行 SELECT 查询。

问题：“查询执行失败”

• 检查：你的 SQL 语法是否正确。
• 检查：你引用的表和列是否存在。
• 检查：你的数据库用户是否对表具有 SELECT 权限。

配置问题

问题：MCP 服务器未出现在 Claude Desktop 客户端中

• 解决方案：重启 Claude Desktop。
• 检查：验证 .mcpb 文件是否正确安装。
• 检查：查看 Claude Desktop 控制台中是否有任何错误消息。

问题：环境变量未显示

• 解决方案：安装后重启 Claude Desktop。
• 检查：确保扩展在 设置 > 功能 中已启用。

问题：无法配置数据库设置

• 解决方案：确保所有必需的环境变量都已填写。
• 检查：验证你的数据库凭据是否正确。

💻 使用示例

获取数据库表

使用 get-all-tables 工具检索数据库模式中的所有表。

执行查询

使用 execute-sql-query 工具执行 SELECT 语句，例如：

SELECT * FROM users LIMIT 10;

🔧 技术细节

系统要求

• PostgreSQL 数据库（版本 9.0 或更高）
• 能够访问你的 PostgreSQL 服务器的网络

依赖项

• Node.js 运行时
• PostgreSQL 客户端库
• MCP（模型上下文协议）框架

项目结构

postgres-connector/
├── src/
│   └── server.ts          # 主 MCP 服务器实现
├── package.json           # Node.js 依赖项
├── manifest.json          # MCP 扩展清单
├── icon.png              # 扩展图标
└── postgres-connector.mcpb # 编译后的扩展包

📄 许可证

本项目采用 MIT 许可协议，详情请参阅 LICENSE 文件。

作者

Marty Markenson

• 邮箱：martyamark@gmail.com
• 领英：Marty Markenson

需要帮助？ 在本仓库中创建一个 issue 或联系 martymarkenson。