PostgreSQL MCP Server

PostgreSQL MCP Server

一个基于 Model Context Protocol (MCP) 的 PostgreSQL 数据库服务器，允许 AI 助手通过 MCP 协议直接查询 PostgreSQL 数据库。

功能特性

• ✅ 通过 MCP 协议执行任意 SQL 查询
• ✅ 支持命令行参数和环境变量两种配置方式
• ✅ 使用 asyncpg 实现异步连接池，提高性能
• ✅ 支持在 Cursor、Claude Desktop 等支持 MCP 的客户端中使用
• ✅ 可通过 Smithery 发布和分发

安装

1. 克隆仓库

git clone https://github.com/zzhRooT1998/postgresql-mcp-server.git
cd postgresql-mcp-server

2. 安装依赖

pip install -r requirements.txt

3. 依赖说明

• asyncpg>=0.29.0 - PostgreSQL 异步数据库驱动
• mcp>=1.26.0,<2.0.0 - Model Context Protocol SDK

使用方法

方式一：命令行参数

python postgresql-mcp.py \
  --user your_username \
  --password your_password \
  --database your_database \
  --host localhost \
  --port 5432

方式二：环境变量

export MCPUSER=your_username
export MCPPASSWORD=your_password
export MCPDATABASE=your_database
export MCPHOST=localhost
export MCPPORT=5432

python postgresql-mcp.py

注意：命令行参数优先级高于环境变量。

在 Cursor 中配置

在 Cursor 的设置中添加以下 MCP 服务器配置：

{
  "mcpServers": {
    "postgresql-mcp-server": {
      "command": "python",
      "args": [
        "postgresql-mcp.py",
        "--user", "your_username",
        "--password", "your_password",
        "--database", "your_database",
        "--host", "localhost",
        "--port", "5432"
      ],
      "cwd": "/path/to/postgresql-mcp-server"
    }
  }
}

Windows 路径示例

{
  "mcpServers": {
    "postgresql-mcp-server": {
      "command": "python",
      "args": [
        "postgresql-mcp.py",
        "--user", "your_username",
        "--password", "your_password",
        "--database", "your_database",
        "--host", "localhost",
        "--port", "5432"
      ],
      "cwd": "D:\\pyApp\\postgresql-mcp-server"
    }
  }
}

在 Smithery 中发布

本项目已配置 smithery.yaml，可以通过 Smithery CLI 发布：

npx @smithery/cli publish --name @zzh/postgresql-mcp-server --transport stdio

发布后，其他用户可以通过 Smithery 目录一键安装你的 MCP 服务器。

可用工具

query

执行任意 SQL 查询，返回行数据的字符串列表。

参数：

• sql (string): 要执行的 SQL 查询语句

示例：

SELECT * FROM device_instance LIMIT 10;

返回：

• 每行记录以字典字符串形式返回，方便在聊天界面中展示

配置参数

扫描模式

如果未提供数据库凭据（MCPUSER 和 MCPPASSWORD），服务器将进入扫描模式，返回 None 配置。这允许 Smithery 等工具在发布前扫描服务器元数据，而无需实际连接数据库。

项目结构

postgresql-mcp-server/
├── postgresql-mcp.py    # 主程序文件
├── requirements.txt     # Python 依赖
├── smithery.yaml        # Smithery 发布配置
└── README.md            # 本文件

开发说明

连接池管理

• 使用 asyncpg.Pool 实现连接池，在 MCP 进程生命周期内复用
• 连接池采用懒加载策略，首次使用时才创建
• 自动检测连接池关闭状态，必要时重新创建

配置加载

• 配置信息在首次加载后缓存到全局变量 DB_CONFIG
• 支持命令行参数和环境变量两种方式
• 命令行参数优先级高于环境变量

许可证

本项目采用 MIT 许可证。

贡献

欢迎提交 Issue 和 Pull Request！

相关链接

• Model Context Protocol 官方文档
• Smithery 文档
• asyncpg 文档