MCP Postgres Query Server

MCP Postgres 查询服务

这是一个用于以只读模式查询 PostgreSQL 数据库的模型上下文协议（MCP）服务实现，旨在与 Claude Desktop 和其他 MCP 客户端配合使用。

概述

本项目实现了一个模型上下文协议（MCP）服务，提供：

1. 安全的 PostgreSQL 数据库只读接口
2. 通过 MCP 协议与 Claude Desktop 集成
3. SQL 查询验证，确保只执行 SELECT 查询
4. 查询超时保护（10 秒）

前置条件

• Node.js（v14 或更高版本）
• npm（随 Node.js 一同安装）
• PostgreSQL 数据库（通过命令行提供连接详情）

安装

# Clone the repository
git clone https://github.com/RathodDarshil/mcp-postgres-query-server.git
cd mcp-postgres-query-server

# Install dependencies
npm install

# Build the project
npm run build

连接到 Claude Desktop

你可以配置 Claude Desktop，使其自动启动并连接到 MCP 服务：

1. 打开 Claude Desktop 配置文件：

   • 打开 Claude Desktop
   • 前往 Settings > Developer > Edit Config
   • 这将使用默认文本编辑器打开配置文件

2. 在 claude_desktop_config.json 的 mcpServers 部分中添加 postgres-query-server：

{
    "mcpServers": {
        "postgres-query": {
            "command": "node",
            "args": [
                "/path/to/your/mcp-postgres-query-server/dist/index.js",
                "postgresql://username:password@hostname:port/database"
            ]
        }
    }
}

3. 将 /path/to/your/ 替换为项目目录的实际路径。
4. 将 PostgreSQL 连接字符串替换为实际的数据库凭据。
5. 保存文件并重启 Claude Desktop。此时，MCP 服务应会显示在 Settings 中的 MCP 服务选择下拉菜单里。

配置示例

以下是包含 postgres-query 的完整配置文件示例：

{
    "mcpServers": {
        "postgres-query": {
            "command": "node",
            "args": [
                "/Users/darshilrathod/mcp-servers/mcp-postgres-query-server/dist/index.js",
                "postgresql://user:password@localhost:5432/mydatabase"
            ]
        }
    }
}

更新配置

要更新 Claude Desktop 配置：

1. 打开 Claude Desktop
2. 前往 Settings > Developer > Edit Config
3. 修改配置文件
4. 保存文件
5. 重启 Claude Desktop，使更改生效
6. 如果你更新了 MCP 服务代码，请务必在重启前使用 npm run build 重新构建

功能

• 数据库只读访问：出于安全考虑，仅允许 SELECT 查询
• 查询验证：阻止可能有害的 SQL 操作
• 超时保护：运行时间超过 10 秒的查询会自动终止
• MCP 协议支持：完整实现模型上下文协议
• JSON 响应格式：以结构化 JSON 格式返回查询结果

API

工具

query-postgres

针对已配置的 PostgreSQL 数据库执行只读 SQL 查询。

参数：

• query（字符串）：要执行的 SQL SELECT 查询

响应：

• 包含以下内容的 JSON 对象：
  • rows：结果集中的行
  • rowCount：返回的行数
  • fields：列元数据

示例：

query-postgres: SELECT * FROM users LIMIT 5

开发

主服务实现在 src/index.ts 中。主要组件：

• PostgreSQL 连接池设置
• 查询验证逻辑
• MCP 服务配置
• 工具和资源定义

要修改服务的行为，你可以：

• 编辑 isReadOnlyQuery() 中的查询验证逻辑
• 为 MCP 服务添加其他工具或资源
• 修改查询超时时长（当前为 10 秒）

安全注意事项

• 服务会验证所有查询，确保其为只读
• 与数据库的连接使用 SSL
• 查询超时机制可防止资源耗尽
• 不允许执行写入操作
• 数据库凭据通过命令行参数直接传入，不存储在文件中

许可证

ISC

贡献

欢迎贡献！欢迎提交 Pull Request。