Postgres MCP 服务器

关键词

PostgreSQLCode ModeJSON-RPCOAuth 2.1HTTP Transport

使用说明

  • 项目简介
    • 该仓库实现了一个基于 MCP 的后端服务器，用于让 AI 助手通过统一的上下文服务访问 PostgreSQL 数据库、执行工具（工具集合如查询、DDL、性能分析等）以及弹性渲染的 Prompt。服务器通过 JSON-RPC 与客户端通信，并提供多种传输方式（标准输入输出、HTTP 传输和 SSE 传输），包含会话管理、能力声明以及安全控制（如 OAuth 2.1）。
  • 主要功能点
    • 资源(Resource) 与 提供的数据访问能力：提供关于数据库的结构、健康、性能等信息的资源集合，便于 AI 客户端在不写 SQL 的情况下获取上下文。
    • 工具(Tools) 注册与执行：提供一组预定义的数据库工具，允许 MCP 客户端通过 JSON-RPC 调用执行数据库操作、模式分析、索引优化等任务。
    • 提示模板(Prompts)：内置智能提示，用于引导 AI 客户端在复杂任务中的工作流和分步操作。
    • Code Mode：在 Code Mode 下，AI 可以在沙箱中一次性执行多步骤的数据库操作，显著减少代币消耗。
    • HTTP/SSE 传输与安全：支持现代的 HTTP 传输和 SSE 传输，且可覆盖 OAuth 2.1 的保护资源、令牌校验、以及按工具分配的细粒度权限控制。
    • 认证与授权：内建 OAuth 相关组件，支持令牌校验、作用域检查和错误格式化，确保对工具的访问受控。
    • 会话与生命周期管理：对 MCP 会话进行初始化、维护和终止，支持并发连接与并发工具调用。
  • 安装与运行步骤
    • 克隆仓库并安装依赖
    • 构建项目
    • 启动服务器（示例：HTTP 传输，端口 3000，连接到 PostgreSQL，默认工具筛选为 starter）
    • 客户端将通过 MCP 配置连接并使用工具、资源和提示
  • 服务器配置（MCP 客户端配置示例说明）
    • 名称：postgres-mcp
    • 启动命令与参数（客户端需配置，不是服务器端代码，客户端将连接到服务器）：
    • 服务器名称: postgres-mcp
    • 启动命令: node
    • 参数示例: dist/cli.js, --transport, http, --port, 3000, --postgres, postgres://<用户名>:<密码>@<数据库主机>:5432/<数据库名>, --tool-filter starter
    • 环境变量示例（可选）: POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_USER=postgres POSTGRES_PASSWORD=your_password POSTGRES_DATABASE=postgres
    • 说明：以上信息用于 MCP 客户端在真实运行环境中的连接配置，客户端需要提供 server name、command、args（以及可选 env），以便通过 MCP 客户端启动并连接到服务器。实际连接字符串请按自身数据库实际地址及凭据替换，且不要在公开环境中暴露敏感信息。
  • 基本使用方法
    • 启动服务器：通过服务器提供的命令行入口以 HTTP 传输方式启动，例如 node dist/cli.js --transport http --port 3000 --postgres "postgres://用户名:密码@localhost:5432/数据库" --tool-filter starter
    • 客户端连接：使用 MCP SDK 客户端连接到 http://<服务器地址>:3000/mcp 进行初始化、列出工具、执行工具、订阅资源与提示等。
    • 使用 Code Mode 以降低代币消耗：在工具筛选中包含 codemode，或显式启用 codemode 作为唯一工具，以在沙箱中执行多步操作。
    • 安全性与部署：如在生产环境中启用 OAuth 2.1，请配置资源服务、JWKS URI、发行者、受众等，并在传输层开启相应的认证与授权检查。
  • 额外信息
    • 本实现包含对 MCP 协议核心功能的完整实现：MCP JSON-RPC 请求处理、响应、会话管理、工具与资源注册、Prompts 渲染、以及多传输协作等。
    • 已包含单元测试与端到端测试，用于验证 HTTP/SSE 传输、工具执行、认证与安全性等方面的行为。

服务器信息

访问项目