# PostgreSQL MCP Server

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

<a href="https://glama.ai/mcp/servers/@zzhRooT1998/postgresql-mcp-server2">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@zzhRooT1998/postgresql-mcp-server2/badge" />
</a>

## 功能特性

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

## 安装

### 1. 克隆仓库

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

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 依赖说明

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

## 使用方法

### 方式一：命令行参数

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

### 方式二：环境变量

```bash
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 服务器配置：

```json
{
  "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 路径示例

```json
{
  "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 之前，请确保完成以下步骤：

1. **创建 GitHub Release**
   - 访问你的 GitHub 仓库：`https://github.com/zzhRooT1998/postgresql-mcp-server`
   - 点击右侧 "Releases" → "Create a new release"
   - 创建标签（如 `v1.0.0`）并填写发布说明
   - 发布后，Smithery 才能识别你的 MCP 服务器

2. **确保所有必需文件已提交**
   - ✅ `LICENSE` - MIT 许可证文件
   - ✅ `glama.json` - Glama 元数据文件
   - ✅ `Dockerfile` - Docker 配置文件（用于服务器检查）
   - ✅ `smithery.yaml` - Smithery 配置

### 发布方式

#### 方式一：使用 Smithery CLI

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

#### 方式二：通过 Smithery 网站

1. 访问 [smithery.ai/new](https://smithery.ai/new)
2. 选择 "From GitHub repository"
3. 输入仓库地址：`zzhRooT1998/postgresql-mcp-server`
4. 完成发布流程

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

## 可用工具

### `query`

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

**参数：**
- `sql` (string): 要执行的 SQL 查询语句

**示例：**
```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！

## 相关链接

- [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)
- [Smithery 文档](https://smithery.ai/docs)
- [asyncpg 文档](https://magicstack.github.io/asyncpg/)