AI导哈

PostgreSQL自托管服务器

一个基于TypeScript的自托管PostgreSQL MCP服务器，提供流式HTTP端点和只读数据库内省工具。

  • by IordanisKokk
  • PLpgSQL
  • 本地部署
  • 更新于
在 GitHub 查看 IordanisKokk/postgres-mcp

使用说明

postgres mcp服务器

TypeScript中的自托管PostgreSQL MCP服务器，具有可流式HTTP端点和只读数据库自检工具。

当前范围

  • test_connection
  • list_tables
  • describe_table
  • list_schemas

路线图

看 ROADMAP.md 对于计划中的工具和平台路线图。

项目结构

  • src/http.ts：Express服务器、流式HTTP传输、会话处理和健康路由
  • src/server.ts：MCP服务器创建、工具注册和工具调度
  • src/tools/：精简工具包装器加Zod输入模式
  • src/db/schemaPolicy.ts：标识符验证和架构访问策略助手
  • src/db/resolveTable.ts：共享表查找和歧义处理
  • src/db/queries/：工具拥有的SQL模块
  • src/config/env.ts：环境解析和规范化
  • src/utils/errors.ts：应用程序错误形状和错误规范化

需求

  • Node.js 20+
  • npm
  • 可访问的PostgreSQL数据库
  • 如果你想使用本地测试栈，可以使用Docker和Docker Compose

配置

复制 .env.example 到 .env 并根据需要调整值。

cp .env.example .env

例子：

DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/postgres
PORT=3000
MCP_PATH=/mcp
QUERY_TIMEOUT_MS=10000
MAX_ROWS=200
ALLOWED_SCHEMAS=public

环境变量：

  • DATABASE_URL：Postgres连接字符串
  • PORT：MCP服务器的HTTP端口
  • MCP_PATH：MCP端点暴露的路径
  • QUERY_TIMEOUT_MS：语句和查询超时（毫秒）
  • MAX_ROWS：保留用于行限制工具，如未来的数据预览工具
  • ALLOWED_SCHEMAS：可选的逗号分隔模式列表；空意味着没有敌意

笔记：

  • 使用 host.docker.internal 当数据库在macOS或Windows上的主机上运行时。
  • 在Linux上，使用可从您的环境访问的主机/IP。

在本地运行

安装依赖项：

npm install

在开发模式下启动服务器：

npm run dev

构建生产输出：

npm run build

启动已编译的服务器：

npm run start

默认端点：

  • MCP： http://localhost:3000/mcp
  • 健康： http://localhost:3000/health

使用Docker Compose运行

docker-compose up --build

测试数据库堆栈

对于可重复的本地检查，请在中使用种子堆栈 test-database/README.md.

该堆栈运行：

  • 种子PostgreSQL实例
  • 此MCP服务器位于同一Docker网络中

这是端到端手动验证当前工具的最简单方法。

添加到Codex MCP配置

使用流式HTTP MCP传输指向：

http://localhost:3000/mcp

例子：

[mcp_servers.postgres]
url = "http://localhost:3000/mcp"

如果您的Codex版本要求提供传输详细信息，请保持相同的URL并选择可流式传输的HTTP。

工具参考

test_connection

目的：

  • 验证配置 DATABASE_URL
  • 返回基本服务器元数据

输入：

{}

输出形状：

{
  "ok": true,
  "latency_ms": 7,
  "database": "app_db",
  "current_user": "readonly_user",
  "server_version": "PostgreSQL 16...",
  "server_time": "2026-03-20T12:00:00.000Z"
}

list_tables

目的：

  • 列出非系统表
  • 可选地筛选到一个架构
  • 可选地包括视图

输入字段：

  • schema：可选字符串
  • include_views：可选布尔值，默认值 false

示例输入：

{
  "schema": "public",
  "include_views": false
}

输出形状：

{
  "tables": [
    {
      "schema": "public",
      "name": "users",
      "type": "BASE TABLE"
    }
  ]
}

describe_table

目的：

  • 返回列元数据
  • 返回主键元数据
  • 返回外键元数据

输入字段：

  • table：必填字符串
  • schema：可选字符串；当表存在于多个模式中时需要

示例输入：

{
  "schema": "public",
  "table": "users"
}

输出包括：

  • schema
  • table
  • columns
  • primary_key
  • foreign_keys

验证和错误

工具输入模式是严格的。在工具逻辑运行之前，Zod会拒绝未知字段。

当前应用程序级错误代码：

  • VALIDATION_ERROR
  • SCHEMA_NOT_ALLOWED
  • NOT_FOUND
  • AMBIGUOUS_TABLE
  • INTERNAL_ERROR

安全和行为

  • 只读内省SQL
  • 未暴露突变工具
  • 标识符验证 schema 和 table
  • 可选的架构限制，通过 ALLOWED_SCHEMAS
  • 系统模式被排除在自省路径之外
  • DB语句/查询超时通过env配置

状态

DB/查询架构重构已被拆分为更小的模块和 src/db/introspection.ts 已删除。接下来的主要工作项是MCP服务器/运行时清理、回归检查和其他只读工具。

相关 MCP