MCP PostgreSQL Server (有状态和双传输)

一个提供HTTP和Stdio两种传输方式与PostgreSQL数据库交互的Model Context Protocol (MCP)服务器。该服务器通过这两种传输方法暴露数据库资源和工具，允许在不同环境中灵活集成。

特性

• 双传输支持：HTTP（StreamableHTTPServerTransport）和Stdio（StdioServerTransport）
• 数据库资源：列出表并检索模式信息
• 查询工具：执行只读SQL查询
• 有状态会话：HTTP传输支持会话管理
• Docker支持：两种传输方式的容器化部署
• 生产就绪：优雅关闭、错误处理和日志记录

快速开始

环境设置

必须传递数据库凭证：

1. 作为环境变量

# PostgreSQL 数据库连接字符串
export POSTGRES_URL=your_connection_string

# 如果未提供 POSTGRES_URL，则需要 PostgreSQL 数据库配置
export POSTGRES_USERNAME=your_username
export POSTGRES_PASSWORD=your_password
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432 # 默认值
export POSTGRES_DATABASE=your_database

# HTTP 服务器配置
# 下面是默认值
export PORT=3000
export HOST=0.0.0.0

# CORS 配置（逗号分隔的允许来源列表）
# 下面是默认值
export CORS_ORIGIN=http://localhost:8080,http://localhost:3000

# 环境
# 下面是默认值
export NODE_ENV=development

2. 或者在工作目录中（npx 命令运行的目录）： 创建一个 .env 文件（该包使用 dotenv 包）

# .env.example
# PostgreSQL 数据库配置
POSTGRES_USERNAME=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=localhost
POSTGRES_DATABASE=your_database

# HTTP 服务器配置
PORT=3000
HOST=0.0.0.0

# CORS 配置（逗号分隔的允许来源列表）
CORS_ORIGIN=http://localhost:8080,http://localhost:3
000

# 环境
NODE_ENV=development

使用 npx 运行

1. 从这里下载 node.js 和 npm
2. 运行包。默认情况下，它将在端口 3000 上运行流式 HTTP：

npx @ahmedmustahid/postgres-mcp-server
# 或 npx @ahmedmustahid/postgres-mcp-server --port 3000 --verbose

3. 对于 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 compose 包：uv add podman-compose（或 uv sync 同步 pyproject.toml 中的包）

# 获取环境变量
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 Desktop 窗口中验证

从 Claude Desktop 使用 MCP 服务器

提示：显示去年的 sales 表。

使用 MCP Inspector 测试

首先，安装 node.js 和 npm，并按照上述说明构建项目。 安装 MCP Inspector：说明这里

检查 Stdio MCP 服务器

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

检查流式 HTTP MCP 服务器

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

npx @ahmedmustahid/postgres-mcp-server

从另一个终端运行 mcp inspector

npx @modelcontextprotocol/inspector

从下拉菜单选择 Streamable HTTP，并在 URL 中插入 http://localhost:3000/mcp（默认）。

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	环境模式	development	否

资源

Hello World (hello://world)

用于测试的简单问候消息。

数据库表 (database://tables)

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

数据库模式 (database://tables/{tableName}/schema)

返回特定表的列信息。

工具

查询

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

参数：

• sql (字符串)：要执行的 SQL 查询

传输差异

功能	HTTP 传输	Stdio 传输
会话管理	✅ 有状态会话	❌ 无状态
并发连接	✅ 多个客户端	❌ 单个进程
Web 集成	✅ REST API 兼容	❌ 仅 CLI
交互使用	✅ 通过 HTTP 客户端	✅ 直接 stdio
Docker 部署	✅ Web 服务	✅ CLI 容器

健康检查

HTTP 服务器包括一个基本的健康检查端点，可通过 /health 端点进行 GET 请求访问（返回 405 方法不允许，确认服务器响应）。

故障排除

常见问题

1. 数据库连接错误

   # 检查 .env 中的数据库凭证
   # 确保 PostgreSQL 正在运行且可访问
   

2. 端口已被占用

   # 更改 .env 中的 PORT 或停止冲突的服务
   lsof -i :3000
   

3. Docker 构建问题

   # 清除 Docker 缓存
   npm run docker:clean
   docker system prune -a
   

4. 会话管理（HTTP）

   # 会话存储在内存中，服务器重启时会重置
   # 对于生产环境，请考虑实现持久会话存储
   

开发

添加新资源

1. 在 src/resources/ 中创建一个新文件
2. 实现资源注册函数
3. 将其添加到 src/server/server.ts

添加新工具

1. 在 src/tools/ 中创建一个新文件
2. 实现工具注册函数
3. 将其添加到 src/server/server.ts

许可证

MIT

贡献

请阅读贡献指南并向主仓库提交拉取请求。