Which integrations are available for this server?

Allows AI assistants to interact with PostgreSQL databases by executing SQL queries and managing data through the Model Context Protocol.

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/Glama 中发布

发布前准备

在发布到 Smithery/Glama 之前，请确保完成以下步骤：

创建 GitHub Release
- 访问你的 GitHub 仓库：https://github.com/zzhRooT1998/postgresql-mcp-server
- 点击右侧 "Releases" → "Create a new release"
- 创建标签（如 v1.0.0）并填写发布说明
- 发布后，Smithery 才能识别你的 MCP 服务器
确保所有必需文件已提交
- ✅ LICENSE - MIT 许可证文件
- ✅ glama.json - Glama 元数据文件
- ✅ Dockerfile - Docker 配置文件（用于服务器检查）
- ✅ smithery.yaml - Smithery 配置

发布方式

方式一：使用 Smithery CLI

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

方式二：通过 Smithery 网站

访问 smithery.ai/new
选择 "From GitHub repository"
输入仓库地址：zzhRooT1998/postgresql-mcp-server
完成发布流程

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

可用工具

`query`

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

参数：

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

示例：

SELECT * FROM device_instance LIMIT 10;

返回：

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

配置参数

参数	环境变量	命令行参数	必填	默认值	说明
用户名	`MCPUSER`	`--user`	✅	-	PostgreSQL 用户名
密码	`MCPPASSWORD`	`--password`	✅	-	PostgreSQL 密码
数据库名	`MCPDATABASE`	`--database`	✅	-	要连接的数据库名
主机地址	`MCPHOST`	`--host`	✅	-	PostgreSQL 主机地址
端口	`MCPPORT`	`--port`	❌	`5432`	PostgreSQL 端口号

扫描模式

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

项目结构

postgresql-mcp-server/
├── postgresql-mcp.py    # 主程序文件
├── requirements.txt     # Python 依赖
├── smithery.yaml        # Smithery 发布配置
├── glama.json           # Glama/Smithery 元数据文件
├── Dockerfile           # Docker 镜像配置（用于服务器检查）
├── LICENSE              # MIT 许可证
└── README.md            # 本文件

开发说明

连接池管理

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

配置加载

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

许可证

本项目采用 MIT 许可证。

贡献

欢迎提交 Issue 和 Pull Request！

postgresql-mcp-server