@hamaster/pgsql-mcp-server

v1.0.3

Published

5 months ago

PostgreSQL MCP Server - 提供PostgreSQL数据库操作工具

0High
0Medium
0Low

hamaster

mcp postgresql postgres database model-context-protocol

PostgreSQL MCP Server

一个用于操作PostgreSQL数据库的Model Context Protocol (MCP)服务器。提供列举表、查询表结构、管理插件、执行SQL查询和更新等功能。

功能特性

列举指定schema下的所有表及其注释
获取表的完整数据结构（字段名称、类型、注释、主键、外键等）
列举所有已安装的PostgreSQL插件（extensions）
安装PostgreSQL插件
执行SELECT查询并返回JSON格式结果（使用占位符防止SQL注入）
执行INSERT、UPDATE、DELETE等操作（使用占位符防止SQL注入）
执行TRUNCATE操作快速清空表数据

安装

全局安装（推荐）

npm install -g pgsql-mcp-server

本地安装

cd pgsql-mcp-server
npm install

配置

创建 .env 文件并配置PostgreSQL连接参数：

cp .env.example .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运行

npx -y pgsql-mcp-server

在MCP Hub中配置

在MCP Hub的配置文件中添加以下配置：

{
  "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"
      }
    }
  }
}

本地运行

npm start

可用工具

1. pgsql_list_tables

列举PostgreSQL数据库指定schema下的所有表及其注释。

参数：

schema (string, 可选): Schema名称，默认为public

返回示例：

{
  "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

返回示例：

{
  "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）。

参数：

无需参数

返回示例：

{
  "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

返回示例：

{
  "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"]

返回示例：

{
  "success": true,
  "schema": "public",
  "row_count": 3,
  "data": [
    {
      "id": 11,
      "name": "John Doe",
      "email": "[email protected]",
      "status": "active"
    },
    {
      "id": 12,
      "name": "Jane Smith",
      "email": "[email protected]",
      "status": "active"
    },
    {
      "id": 13,
      "name": "Bob Johnson",
      "email": "[email protected]",
      "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", "[email protected]", "active"]

返回示例：

{
  "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

返回示例：

{
  "success": true,
  "schema": "public",
  "table": "users",
  "message": "Table \"public.users\" truncated successfully"
}

安全特性

SQL注入防护

所有SQL操作都必须使用PostgreSQL的占位符（$1, $2等）传递参数，这能有效防止SQL注入攻击：

// ✅ 正确：使用占位符
sql: "SELECT * FROM users WHERE id = $1"
params: [1]

// ❌ 错误：直接拼接SQL（会导致SQL注入风险）
sql: "SELECT * FROM users WHERE id = 1"  // 不要这样做！

危险操作限制

出于安全考虑，以下操作被禁止：

DROP DATABASE
DROP SCHEMA

完整工作流程示例

列举所有表
- 工具: pgsql_list_tables
- 参数: schema: public
查看表结构
- 工具: pgsql_describe_table
- 参数: schema: public, table: users
列举已安装的插件
- 工具: pgsql_list_extensions
安装插件
- 工具: pgsql_install_extension
- 参数: extension: uuid-ossp, schema: public
查询数据（使用占位符）
- 工具: pgsql_query
- 参数: schema: public, sql: "SELECT * FROM users WHERE id > $1", params: [10]
插入数据（使用占位符）
- 工具: pgsql_execute
- 参数: schema: public, sql: "INSERT INTO users (name, email) VALUES ($1, $2)", params: ["John", "[email protected]"]
更新数据（使用占位符）
- 工具: pgsql_execute
- 参数: schema: public, sql: "UPDATE users SET email = $1 WHERE id = $2", params: ["[email protected]", 1]
清空表
- 工具: 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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

PostgreSQL MCP Server

功能特性

安装

全局安装（推荐）

本地安装

配置

环境变量说明

使用方法

通过npx运行

在MCP Hub中配置

本地运行

可用工具

1. pgsql_list_tables

2. pgsql_describe_table

3. pgsql_list_extensions

4. pgsql_install_extension

5. pgsql_query

6. pgsql_execute

7. pgsql_truncate_table

安全特性

SQL注入防护

危险操作限制

完整工作流程示例

技术栈

PostgreSQL特性支持

故障排除

连接失败

权限错误

插件安装失败

SQL执行错误

许可证