PostgreSQL MCP Server (Read-Write)

PostgreSQL MCP Server (Read-Write)

Supports CRUD and DDL operations on PostgreSQL databases via MCP, enabling query, insert, update, delete, and schema changes through natural language.

Category
访问服务器

README

PostgreSQL MCP Server (Read-Write)

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

npm version npm downloads

📦 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', 'john@example.com')"
}

3. update

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

参数:

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

示例:

{
  "sql": "UPDATE users SET email = 'newemail@example.com' 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 mcp-server-postgresql-rw@1.0.0

⚠️ 注意: 撤销后 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

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选