AI导哈

PostgreSQL服务器协议

一个提供HTTP和Stdio两种传输方式与PostgreSQL数据库交互的模型上下文协议(MCP)服务器，适用于需要灵活集成数据库资源的开发环境。

  • by sreedhag
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 sreedhag/postgres-mcp-server

使用说明

MCP PostgreSQL服务器（有状态和双传输）

一种模型上下文协议（MCP）服务器，提供HTTP和Stdio传输，用于与PostgreSQL数据库交互。此服务器通过两种传输方法公开数据库资源和工具，允许在不同环境中灵活集成。

特性

  • 双重运输支持：HTTP（流式HTTP服务器传输）和Stdio（Stdio服务器传输）
  • 数据库资源：列出表并检索架构信息
  • 查询工具：执行只读SQL查询
  • 有意义的会议：HTTP传输支持会话管理
  • Docker支持：两种运输方式的集装箱化部署
  • 生产就绪：优雅的关机、错误处理和日志记录

快速开始

环境设置

数据库凭据必须以以下方式传递：

  1. 任一环境变量
# PostgreSQL Database Connection String
export POSTGRES_URL=your_connection_string

# PostgreSQL Database Configuration if POSTGRES_URL is not provided
export POSTGRES_USERNAME=your_username
export POSTGRES_PASSWORD=your_password
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432 # this is the default
export POSTGRES_DATABASE=your_database

# HTTP Server Configuration
# Following are the default values
export PORT=3000
export HOST=0.0.0.0

# CORS Configuration (comma-separated list of allowed origins)
# Following are the default values
export CORS_ORIGIN=http://localhost:8080,http://localhost:3000

# Environment
# Following are the default values
export NODE_ENV=development
  1. 或者在工作目录中（ npx 将运行命令）： 创建一个 .env 文件（包使用 dotenv 包装）
# .env.example
# PostgreSQL Database Configuration
POSTGRES_USERNAME=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=localhost
POSTGRES_DATABASE=your_database

# HTTP Server Configuration
PORT=3000
HOST=0.0.0.0

# CORS Configuration (comma-separated list of allowed origins)
CORS_ORIGIN=http://localhost:8080,http://localhost:3000

# Environment
NODE_ENV=development

使用运行 npx

  1. 从以下网址下载node.js和npm 这里
  2. 运行包。默认情况下，它将在端口3000上运行可流式传输的http：
npx @ahmedmustahid/postgres-mcp-server
# or npx @ahmedmustahid/postgres-mcp-server --port 3000 --verbose
  1. 对于stdio传输：
npx @ahmedmustahid/postgres-mcp-server stdio
# npx @ahmedmustahid/postgres-mcp-server stdio --verbose

环境设置

复制环境模板

cp .env.example .env

编辑数据库凭据

nano .env

Podman（或Docker）使用

  1. 从以下位置安装podman 这里
  2. 安装 uv 从 这里
  3. 安装podman组合包： uv add podman-compose （或 uv sync 在中同步包 pyproject.toml)
#get the environment variables
set -a
source .env
set +a
podman machine start
make podman-up

使用Claude Desktop进行测试

首先，安装node.js和npm，按照上面的说明构建项目。 编辑您的 claude_desktop_config.json

{
  "mcpServers": {
    "postgres-mcp-server": {
      "command": "npx",
      "args": [
        "@ahmedmustahid/postgres-mcp-server",
        "stdio"
      ],
      "env": {
        "POSTGRES_USERNAME": "your-username",
        "POSTGRES_PASSWORD": "your-password",
        "POSTGRES_HOST": "hostname",
        "POSTGRES_DATABASE": "database-name"
      }
    }
  }
}

检查MCP服务器是否已启用

从Claude桌面窗口验证

从Claude Desktop使用MCP服务器

提示：显示 sales 去年的桌子。

使用MCP检查器进行测试

首先，安装node.js和npm，按照上面的说明构建项目。 安装MCP检查器：说明： 这里

检查Stdio MCP服务器

npx @modelcontextprotocol/inspector npx @ahmedmustahid/postgres-mcp-server stdio

检查可流式HTTP MCP服务器

首先，运行服务器（已配置环境的shell）：

npx @ahmedmustahid/postgres-mcp-server

从另一个终端运行mcp检查器

npx @modelcontextprotocol/inspector

选择后 Streamable HTTP 从下拉菜单中插入 http://localhost:3000/mcp（默认）转换为URL。

MCP工具：

MCP资源：

配置

环境变量

您必须在.env文件中指定这些。

变量 描述 默认值 必填
POSTGRES_USERNAME PostgreSQL用户名 - 是
POSTGRES_PASSWORD PostgreSQL密码 - 是
POSTGRES_HOST PostgreSQL主机 - 是
POSTGRES_DATABASE PostgreSQL数据库名称 - 是
PORT HTTP服务器端口 3000 否
HOST HTTP服务器主机 0.0.0.0 否
CORS_ORIGIN 允许的CORS源（逗号分隔） localhost:8080，localhost:3000 否
NODE_ENV 环境模式 开发 否

资源

你好，世界(hello://world)

一条简单的测试问候语。

数据库表(database://tables)

列出公共模式中的所有表及其模式URI。

数据库架构(database://tables/{tableName}/schema)

返回特定表的列信息。

工具

怎么翻译

对数据库执行只读SQL查询。

参数：

  • sql （string）：要执行的SQL查询

运输差异

特性 HTTP传输 标准传输
会话管理 ✅ 有意义的会议 ❌ 无国籍
并发连接 ✅ 多个客户端 ❌ 单一流程
Web集成 ✅ REST API兼容 ❌ 仅限CLI
交互式使用 ✅ 通过HTTP客户端 ✅ 直接输入
Docker部署 ✅ Web服务 ✅ CLI容器

健康检查

HTTP服务器包括一个基本的健康检查端点，可在 /health 带有GET请求的端点（返回405 Method Not Allowed，确认服务器有响应）。

故障排除

常见问题

  1. 数据库连接错误

    # Check your database credentials in .env
# Ensure PostgreSQL is running and accessible

  2. 端口已在使用中

    # Change PORT in .env or stop conflicting services
lsof -i :3000

  3. Docker构建问题

    # Clean Docker cache
npm run docker:clean
docker system prune -a

  4. 会话管理（HTTP）

    # Sessions are stored in memory and will reset on server restart
# For production, consider implementing persistent session storage

发展

添加新资源

  1. 在中创建新文件 src/resources/
  2. 实现资源注册功能
  3. 添加到 src/server/server.ts

添加新工具

  1. 在中创建新文件 src/tools/
  2. 实现刀具注册功能
  3. 添加到 src/server/server.ts

许可证

麻省理工学院

贡献

请阅读贡献指南，并将拉取请求提交到主存储库。

相关 MCP