npm package: @hamaster/pgsql-mcp-server
Description: PostgreSQL MCP Server - 提供PostgreSQL数据库操作工具
Latest version: 1.0.3

# PostgreSQL MCP Server

一个用于操作PostgreSQL数据库的Model Context Protocol (MCP)服务器。提供列举表、查询表结构、管理插件、执行SQL查询和更新等功能。

## 功能特性

- 列举指定schema下的所有表及其注释
- 获取表的完整数据结构（字段名称、类型、注释、主键、外键等）
- 列举所有已安装的PostgreSQL插件（extensions）
- 安装PostgreSQL插件
- 执行SELECT查询并返回JSON格式结果（使用占位符防止SQL注入）
- 执行INSERT、UPDATE、DELETE等操作（使用占位符防止SQL注入）
- 执行TRUNCATE操作快速清空表数据

## 安装

### 全局安装（推荐）

```bash
npm install -g pgsql-mcp-server
```

### 本地安装

```bash
cd pgsql-mcp-server
npm install
```

## 配置

创建 `.env` 文件并配置PostgreSQL连接参数：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=your_password
PG_DATABASE=your_database
PG_SCHEMA=public
```

### 环境变量说明

| 变量名 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| PG_HOST | 否 | localhost | PostgreSQL服务器地址 |
| PG_PORT | 否 | 5432 | PostgreSQL端口 |
| PG_USER | 否 | postgres | PostgreSQL用户名 |
| PG_PASSWORD | 否 | (空) | PostgreSQL密码 |
| PG_DATABASE | 否 | (空) | 数据库名称 |
| PG_SCHEMA | 否 | public | Schema名称 |

## 使用方法

### 通过npx运行

```bash
npx -y pgsql-mcp-server
```

### 在MCP Hub中配置

在MCP Hub的配置文件中添加以下配置：

```json
{
  "mcpServers": {
    "pgsql": {
      "command": "npx",
      "args": ["-y", "pgsql-mcp-server"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "postgres",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "myapp",
        "PG_SCHEMA": "public"
      }
    }
  }
}
```

### 本地运行

```bash
npm start
```

## 可用工具

### 1. pgsql_list_tables
列举PostgreSQL数据库指定schema下的所有表及其注释。

**参数：**
- `schema` (string, 可选): Schema名称，默认为public

**返回示例：**
```json
{
  "success": true,
  "schema": "public",
  "tables": [
    {
      "table_name": "users",
      "comment": "用户表"
    },
    {
      "table_name": "products",
      "comment": "产品表"
    }
  ],
  "count": 2
}
```

### 2. pgsql_describe_table
获取表的完整数据结构，包括字段名称、数据类型、是否为空、默认值、主键、字段注释等详细信息。

**参数：**
- `schema` (string, 可选): Schema名称，默认为public
- `table` (string, 必填): 表名称

**示例：**
```
schema: public
table: users
```

**返回示例：**
```json
{
  "success": true,
  "schema": "public",
  "table": "users",
  "table_comment": "用户表",
  "columns": [
    {
      "field": "id",
      "type": "integer",
      "null": false,
      "key": "PRI",
      "default": "nextval('users_id_seq'::regclass)",
      "comment": "用户ID"
    },
    {
      "field": "name",
      "type": "varchar(100)",
      "null": false,
      "key": "",
      "default": null,
      "comment": "用户姓名"
    },
    {
      "field": "email",
      "type": "varchar(255)",
      "null": false,
      "key": "UNI",
      "default": null,
      "comment": "用户邮箱"
    },
    {
      "field": "created_at",
      "type": "timestamp without time zone",
      "null": false,
      "key": "",
      "default": "now()",
      "comment": "创建时间"
    }
  ],
  "column_count": 4
}
```

### 3. pgsql_list_extensions
列举PostgreSQL数据库中所有已安装的插件（extensions）。

**参数：**
- 无需参数

**返回示例：**
```json
{
  "success": true,
  "extensions": [
    {
      "extension_name": "plpgsql",
      "version": "1.0",
      "schema": "pg_catalog"
    },
    {
      "extension_name": "uuid-ossp",
      "version": "1.1",
      "schema": "public"
    }
  ],
  "count": 2
}
```

### 4. pgsql_install_extension
在PostgreSQL数据库中安装指定的插件（extension）。

**参数：**
- `extension` (string, 必填): 插件名称，例如: uuid-ossp, pgcrypto, postgis等
- `schema` (string, 可选): Schema名称，默认扩展安装到public schema

**示例：**
```
extension: uuid-ossp
schema: public
```

**返回示例：**
```json
{
  "success": true,
  "extension": "uuid-ossp",
  "schema": "public",
  "message": "Extension \"uuid-ossp\" installed successfully in schema \"public\""
}
```

### 5. pgsql_query
执行SELECT查询语句，返回JSON格式的查询结果。**必须使用占位符（$1, $2等）传递参数以防止SQL注入**。

**参数：**
- `schema` (string, 可选): Schema名称，默认为public
- `sql` (string, 必填): SQL SELECT查询语句，必须使用占位符$1, $2等
- `params` (array, 可选): 查询参数数组，对应SQL中的占位符$1, $2等

**示例：**
```
schema: public
sql: SELECT * FROM users WHERE id > $1 AND status = $2
params: [10, "active"]
```

**返回示例：**
```json
{
  "success": true,
  "schema": "public",
  "row_count": 3,
  "data": [
    {
      "id": 11,
      "name": "John Doe",
      "email": "john@example.com",
      "status": "active"
    },
    {
      "id": 12,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "status": "active"
    },
    {
      "id": 13,
      "name": "Bob Johnson",
      "email": "bob@example.com",
      "status": "active"
    }
  ]
}
```

### 6. pgsql_execute
执行INSERT、UPDATE、DELETE等非查询SQL语句，返回执行结果。**必须使用占位符（$1, $2等）传递参数以防止SQL注入**。

**参数：**
- `schema` (string, 可选): Schema名称，默认为public
- `sql` (string, 必填): SQL语句，必须使用占位符$1, $2等
- `params` (array, 可选): 查询参数数组，对应SQL中的占位符$1, $2等

**示例：**
```
schema: public
sql: INSERT INTO users (name, email, status) VALUES ($1, $2, $3)
params: ["Alice", "alice@example.com", "active"]
```

**返回示例：**
```json
{
  "success": true,
  "schema": "public",
  "affected_rows": 1,
  "message": "INSERT executed successfully, affected 1 rows"
}
```

### 7. pgsql_truncate_table
快速清空指定表的所有数据（TRUNCATE操作）。此操作不可逆，会删除表中的所有数据但保留表结构。

**参数：**
- `schema` (string, 可选): Schema名称，默认为public
- `table` (string, 必填): 表名称

**示例：**
```
schema: public
table: users
```

**返回示例：**
```json
{
  "success": true,
  "schema": "public",
  "table": "users",
  "message": "Table \"public.users\" truncated successfully"
}
```

## 安全特性

### SQL注入防护
所有SQL操作都必须使用PostgreSQL的占位符（$1, $2等）传递参数，这能有效防止SQL注入攻击：

```javascript
// ✅ 正确：使用占位符
sql: "SELECT * FROM users WHERE id = $1"
params: [1]

// ❌ 错误：直接拼接SQL（会导致SQL注入风险）
sql: "SELECT * FROM users WHERE id = 1"  // 不要这样做！
```

### 危险操作限制
出于安全考虑，以下操作被禁止：
- DROP DATABASE
- DROP SCHEMA

## 完整工作流程示例

1. **列举所有表**
   - 工具: `pgsql_list_tables`
   - 参数: `schema: public`

2. **查看表结构**
   - 工具: `pgsql_describe_table`
   - 参数: `schema: public, table: users`

3. **列举已安装的插件**
   - 工具: `pgsql_list_extensions`

4. **安装插件**
   - 工具: `pgsql_install_extension`
   - 参数: `extension: uuid-ossp, schema: public`

5. **查询数据（使用占位符）**
   - 工具: `pgsql_query`
   - 参数: `schema: public, sql: "SELECT * FROM users WHERE id > $1", params: [10]`

6. **插入数据（使用占位符）**
   - 工具: `pgsql_execute`
   - 参数: `schema: public, sql: "INSERT INTO users (name, email) VALUES ($1, $2)", params: ["John", "john@example.com"]`

7. **更新数据（使用占位符）**
   - 工具: `pgsql_execute`
   - 参数: `schema: public, sql: "UPDATE users SET email = $1 WHERE id = $2", params: ["newemail@example.com", 1]`

8. **清空表**
   - 工具: `pgsql_truncate_table`
   - 参数: `schema: public, table: temp_table`

## 技术栈

- Node.js >= 18.0.0
- @modelcontextprotocol/sdk ^1.25.2
- pg ^8.11.3

## PostgreSQL特性支持

- ✅ Schema支持（默认public，可自定义）
- ✅ 表注释和字段注释
- ✅ 主键、唯一键、外键识别
- ✅ 扩展（Extensions）管理
- ✅ 占位符参数化查询（防止SQL注入）
- ✅ 连接池管理
- ✅ TRUNCATE操作支持

## 故障排除

### 连接失败
- 检查 `.env` 文件中的连接参数是否正确
- 确认PostgreSQL服务器是否正在运行
- 检查防火墙设置
- 确认pg_hba.conf配置允许连接

### 权限错误
- 确认PostgreSQL用户是否有相应的数据库访问权限
- 检查用户是否有SELECT、INSERT、UPDATE、DELETE权限
- 确认用户是否有指定schema的访问权限

### 插件安装失败
- 确认PostgreSQL服务器上已安装该插件
- 检查用户是否有CREATE EXTENSION权限
- 某些插件需要超级用户权限才能安装

### SQL执行错误
- 检查SQL语法是否正确
- 确认使用占位符而不是直接拼接参数
- 确认表名和字段名是否存在
- 查看返回的错误信息以获取详细原因

## 许可证

MIT