PostgreSQL MCP Server (Read-Write)

这是一个支持 PostgreSQL 数据库增删改查和 DDL 操作的 Model Context Protocol (MCP) 服务器。

📦 npm 包: https://www.npmjs.com/package/mcp-server-postgresql-rw
🐙 GitHub: https://github.com/yanxxcloud/mcp-server-postgresql-rw

功能特性

• ✅ 查询（SELECT）: 执行 SELECT 查询语句，返回查询结果
• ✅ 插入（INSERT）: 向表中插入新数据
• ✅ 更新（UPDATE）: 更新表中的数据
• ✅ 删除（DELETE）: 从表中删除数据
• ✅ DDL 操作: 执行数据定义语言操作（CREATE、ALTER、DROP 等）
• ✅ 通用执行: 执行任意 SQL 语句

快速开始

方式 1: 通过 npm 安装（⭐ 推荐）

最简单的方式，直接从 npm 安装：

npm install -g mcp-server-postgresql-rw

然后在 mcp.json 中配置：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "mcp-server-postgresql-rw",
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
      }
    }
  }
}

或者使用 npx（无需全局安装，推荐）：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": ["-y", "mcp-server-postgresql-rw"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
      }
    }
  }
}

方式 2: 从源码安装

如果你想从源码安装或进行开发：

# 克隆项目
git clone https://github.com/yanxxcloud/mcp-server-postgresql-rw.git
cd mcp-server-postgresql-rw

# 安装依赖
npm install

# 构建项目（可选，如果使用 npx tsx 方式则不需要）
npm run build

然后在 mcp.json 中配置（推荐使用 npx tsx 方式，无需构建）：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/path/to/mcp-server-postgresql-rw/src/index.ts"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
      }
    }
  }
}

3. 重启 Cursor

配置完成后，重启 Cursor 即可使用！

💡 提示:

• ⭐ 推荐使用 npm 安装：最简单快捷，包已构建好，开箱即用
• 使用 npx 方式无需全局安装，每次自动下载最新版本
• 从源码安装适合需要修改代码或参与开发的场景

安装

方式 1: 通过 npm 安装（⭐ 推荐）

最简单的方式，直接从 npm 安装：

npm install -g mcp-server-postgresql-rw

或使用 npx（无需全局安装）：

npx -y mcp-server-postgresql-rw

方式 2: 从源码安装

如果你想从源码安装或进行开发：

# 克隆项目
git clone https://github.com/yanxxcloud/mcp-server-postgresql-rw.git
cd mcp-server-postgresql-rw

# 安装依赖
npm install

# 构建项目（如果使用编译后的文件）
npm run build

配置

通过环境变量配置数据库连接：

方式 1: 使用连接字符串

export POSTGRES_CONNECTION_STRING="postgresql://user:password@localhost:5432/database"

方式 2: 使用单独的参数

export POSTGRES_HOST="localhost"
export POSTGRES_PORT="5432"
export POSTGRES_DATABASE="postgres"
export POSTGRES_USER="postgres"
export POSTGRES_PASSWORD="password"
export POSTGRES_SSL="false"

使用方法

作为 MCP 服务器运行

npm start

开发模式

npm run dev

可用工具

1. query

执行 SELECT 查询语句，返回查询结果。

参数:

• sql (string, 必需): SELECT SQL 查询语句

示例:

{
  "sql": "SELECT * FROM users WHERE age > 18"
}

2. insert

执行 INSERT 语句，向表中插入新数据。

参数:

• sql (string, 必需): INSERT SQL 语句

示例:

{
  "sql": "INSERT INTO users (name, email) VALUES ('John', '[email protected]')"
}

3. update

执行 UPDATE 语句，更新表中的数据。

参数:

• sql (string, 必需): UPDATE SQL 语句

示例:

{
  "sql": "UPDATE users SET email = '[email protected]' WHERE id = 1"
}

4. delete

执行 DELETE 语句，从表中删除数据。

参数:

• sql (string, 必需): DELETE SQL 语句

示例:

{
  "sql": "DELETE FROM users WHERE id = 1"
}

5. execute_ddl

执行 DDL（数据定义语言）语句，包括 CREATE、ALTER、DROP 等操作。

参数:

• sql (string, 必需): DDL SQL 语句

示例:

{
  "sql": "CREATE TABLE products (id SERIAL PRIMARY KEY, name VARCHAR(100), price DECIMAL(10,2))"
}

6. execute

执行任意 SQL 语句（查询、DML 或 DDL）。这是一个通用工具。

参数:

• sql (string, 必需): SQL 语句

示例:

{
  "sql": "SELECT COUNT(*) FROM users"
}

在 Cursor 中配置 MCP

步骤 1: 找到 mcp.json 配置文件

mcp.json 文件通常位于以下位置：

• macOS/Linux: ~/.config/cursor/mcp.json 或 ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
• Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json

如果文件不存在，请创建它。

步骤 2: 配置 mcp.json

打开或创建 mcp.json 文件，添加以下配置。有三种运行方式：

方式 A: 使用 npm 安装（⭐ 最简单，推荐）

直接从 npm 安装，无需构建，开箱即用。

配置方式 A1: 全局安装后使用

npm install -g mcp-server-postgresql-rw

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "mcp-server-postgresql-rw",
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://用户名:密码@主机:端口/数据库名"
      }
    }
  }
}

配置方式 A2: 使用 npx（无需全局安装，推荐）

无需全局安装，每次自动使用最新版本：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": ["-y", "mcp-server-postgresql-rw"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://用户名:密码@主机:端口/数据库名"
      }
    }
  }
}

实际示例：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": ["-y", "mcp-server-postgresql-rw"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://postgres:mypassword@localhost:5432/mydb"
      }
    }
  }
}

方式 B: 使用 npx tsx 直接运行（从源码，无需构建）

这种方式可以直接运行 TypeScript 源文件，无需先执行 npm run build。适合从源码安装的场景。

配置方式 B1: 使用连接字符串

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/yanxx/tools/mcp/postgresql-server-rw/src/index.ts"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://用户名:密码@主机:端口/数据库名"
      }
    }
  }
}

实际示例：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/yanxx/tools/mcp/postgresql-server-rw/src/index.ts"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://postgres:mypassword@localhost:5432/mydb"
      }
    }
  }
}

配置方式 B2: 使用单独参数

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/yanxx/tools/mcp/postgresql-server-rw/src/index.ts"
      ],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "postgres",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_SSL": "false"
      }
    }
  }
}

方式 C: 使用编译后的文件（从源码，需要先构建）

如果你从源码安装并想使用编译后的 JavaScript 文件，需要先构建：

cd /path/to/mcp-server-postgresql-rw
npm install
npm run build

配置方式 C1: 使用连接字符串

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "node",
      "args": ["/path/to/mcp-server-postgresql-rw/dist/index.js"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://用户名:密码@主机:端口/数据库名"
      }
    }
  }
}

实际示例：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "node",
      "args": ["/path/to/mcp-server-postgresql-rw/dist/index.js"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://postgres:mypassword@localhost:5432/mydb"
      }
    }
  }
}

配置方式 C2: 使用单独参数

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "node",
      "args": ["/path/to/mcp-server-postgresql-rw/dist/index.js"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "postgres",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_SSL": "false"
      }
    }
  }
}

三种方式对比

| 特性 | 方式 A (npm/npx) | 方式 B (npx tsx) | 方式 C (编译后) | |------|------------------|------------------|-----------------| | 安装方式 | npm install -g 或 npx | 从源码安装 | 从源码安装 | | 需要构建 | ❌ 不需要 | ❌ 不需要 | ✅ 需要 npm run build | | 启动速度 | ⚡ 最快 | 稍慢（首次需要下载 tsx） | 快 | | 更新方式 | npm update -g 或自动 | 需要 git pull | 需要 git pull + build | | 推荐场景 | ⭐ 生产环境、日常使用 | 开发环境、频繁修改 | 生产环境、稳定版本 |

推荐:

• ⭐ 日常使用推荐方式 A (npm/npx)：最简单快捷，自动更新
• 开发时使用方式 B (npx tsx)：修改代码后无需重新构建

步骤 4: 使用 SSL 连接（可选）

如果数据库需要 SSL 连接，使用 npx tsx 方式：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/yanxx/tools/mcp/postgresql-server-rw/src/index.ts"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:5432/db?sslmode=require"
      }
    }
  }
}

或使用单独参数：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/yanxx/tools/mcp/postgresql-server-rw/src/index.ts"
      ],
      "env": {
        "POSTGRES_HOST": "your-host.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "mydb",
        "POSTGRES_USER": "myuser",
        "POSTGRES_PASSWORD": "mypassword",
        "POSTGRES_SSL": "true"
      }
    }
  }
}

步骤 5: 如果已有其他 MCP 服务器配置

如果你的 mcp.json 中已经有其他服务器配置，只需在 mcpServers 对象中添加新的配置：

{
  "mcpServers": {
    "existing-server": {
      "command": "node",
      "args": ["/path/to/existing/server.js"]
    },
    "postgresql-rw": {
      "command": "node",
      "args": ["/Users/yanxx/tools/mcp/postgresql-server-rw/dist/index.js"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
      }
    }
  }
}

步骤 6: 重启 Cursor

配置完成后，重启 Cursor 以使配置生效。

步骤 7: 验证配置

重启后，在 Cursor 中：

1. 打开命令面板（Cmd+Shift+P 或 Ctrl+Shift+P）
2. 输入 "MCP" 查看可用的 MCP 相关命令
3. 尝试使用 AI 助手，询问它是否可以访问 PostgreSQL 工具

你也可以直接询问 AI：

• "列出可用的 PostgreSQL 工具"
• "查询数据库中的表"
• "执行一个简单的 SELECT 查询"

故障排除

问题 1: 找不到 node 命令

如果系统找不到 node 命令，可以使用完整路径：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/yanxx/tools/mcp/postgresql-server-rw/dist/index.js"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
      }
    }
  }
}

查找 node 路径：

which node

问题 2: 连接失败

检查：

• 数据库服务是否运行
• 连接字符串或参数是否正确
• 防火墙是否允许连接
• 数据库用户是否有足够权限

问题 3: 权限错误

如果使用编译后的文件，确保 dist/index.js 文件有执行权限：

chmod +x /path/to/mcp-server-postgresql-rw/dist/index.js

如果使用 npm 安装，通常不会有权限问题。

问题 4: 查看日志

如果遇到问题，可以查看 Cursor 的日志文件来诊断问题。

发布到 npm

✅ 已发布: 此包已发布到 npm，可以直接使用 npm install -g mcp-server-postgresql-rw 安装。

📦 npm 包地址: https://www.npmjs.com/package/mcp-server-postgresql-rw

如果你想更新版本或重新发布，请按照以下步骤操作：

1. 准备发布

1.1 更新 package.json

确保 package.json 中的信息正确：

• name: 包名（必须是唯一的，检查 npm 上是否已存在）
• version: 版本号
• author: 作者信息
• repository: Git 仓库地址（如果有）
• description: 包描述

1.2 创建 npm 账号

如果还没有 npm 账号，请访问 npmjs.com 注册。

1.3 登录 npm

npm login

输入你的用户名、密码和邮箱。

2. 检查包名是否可用

npm search mcp-server-postgresql-rw

如果包名已被占用，需要在 package.json 中修改 name 字段。

3. 构建项目

npm run build

4. 测试本地安装

在发布前，可以先测试本地安装：

npm pack

这会生成一个 .tgz 文件，你可以本地安装测试：

npm install -g ./mcp-server-postgresql-rw-1.0.0.tgz

5. 发布到 npm

5.1 发布公开包（推荐）

npm publish --access public

5.2 发布私有包（需要付费账号）

npm publish

6. 验证发布

发布成功后，可以在 npm 上搜索你的包：

npm search mcp-server-postgresql-rw

或者访问：https://www.npmjs.com/package/mcp-server-postgresql-rw

7. 更新版本

发布新版本时：

# 更新版本号（会自动更新 package.json）
npm version patch  # 1.0.0 -> 1.0.1 (补丁版本)
npm version minor  # 1.0.0 -> 1.1.0 (小版本)
npm version major  # 1.0.0 -> 2.0.0 (大版本)

# 然后发布
npm publish --access public

8. 撤销发布（如果需要）

如果发布有误，可以在 72 小时内撤销：

npm unpublish [email protected]

⚠️ 注意: 撤销后 24 小时内不能发布相同版本。

发布检查清单

• [ ] 更新 package.json 中的版本号
• [ ] 更新 README.md 中的使用说明
• [ ] 确保代码已构建（npm run build）
• [ ] 测试本地安装（npm pack 和 npm install -g）
• [ ] 确保 .npmignore 配置正确
• [ ] 登录 npm (npm login)
• [ ] 检查包名是否可用
• [ ] 发布 (npm publish --access public)

发布后的使用方式

发布后，其他人可以通过以下方式使用：

全局安装

npm install -g mcp-server-postgresql-rw

然后在 mcp.json 中配置：

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "mcp-server-postgresql-rw",
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
      }
    }
  }
}

使用 npx（无需全局安装）

{
  "mcpServers": {
    "postgresql-rw": {
      "command": "npx",
      "args": ["-y", "mcp-server-postgresql-rw"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
      }
    }
  }
}

安全注意事项

⚠️ 警告: 此服务器允许执行任意 SQL 语句，包括 DDL 和 DML 操作。请确保：

1. 只连接到受信任的数据库
2. 使用具有适当权限的数据库用户
3. 在生产环境中谨慎使用
4. 考虑添加 SQL 注入防护机制

许可证

MIT