AI导哈

PostgreSQL MCP 服务器

PostgreSQL MCP 服务器是一个通过模型上下文协议（MCP）将PostgreSQL数据库暴露给AI助手的服务，支持本地或Kubernetes端口转发连接，所有操作基于数据库用户的权限执行。

  • by ajinkyak302
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 ajinkyak302/postgres-mcp

使用说明

Postgres MCP服务器

A. 模型上下文协议 （MCP）服务器，将PostgreSQL暴露给AI助手。它适用于任何连接（本地或Kubernetes端口转发）和任何数据库用户；操作成功或失败取决于用户的PostgreSQL权限。

概述

Postgres MCP允许AI工具（例如。 光标Claude Desktop）通过一组固定的工具与PostgreSQL数据库交互。默认情况下，服务器不执行任意SQL；它公开了结构化操作（列表表、查询、插入、更改表、创建函数等）。对于高级用例，a run_sql 该工具运行一条语句。所有操作都受数据库用户权限的约束——无法从服务器提升权限。

使用案例：

  • 让AI助手在您所选角色的权限范围内探索模式、运行只读查询或修改数据。
  • 使用只读数据库用户进行安全自检；将角色与DDL一起用于模式更改和迁移。
  • 通过端口转发和使用连接到Kubernetes后面的Postgres localhost 在连接字符串中。

目录

先决条件

  • 转到1.25或更高版本 — 安装Go
  • PostgreSQL --可从运行MCP服务器的主机访问（例如本地或通过 kubectl port-forward)
  • 数据库用户 --任何用户；仅授予您希望AI拥有的权限（例如只读或完整DDL）

安装

从源代码构建

git clone https://github.com/ajinkyak302/postgres-mcp.git
cd postgres-mcp
go build -o postgres-mcp .

二进制 postgres-mcp （或 postgres-mcp.exe 在Windows上）将位于当前目录中。

通过Go安装

如果您的环境有Go并且模块路径与存储库匹配：

go install github.com/ajinkyak302/postgres-mcp@latest

二进制文件被放置在 $GOPATH/bin 或 $HOME/go/bin。确保目录在您的 PATH.

配置

连接字符串

设置 POSTGRES_URL （或 DATABASE_URL)将环境变量转换为有效值 PostgreSQL连接URI:

postgres://USER:PASSWORD@HOST:PORT/DATABASE

  • 当地： 使用 localhost （或 127.0.0.1)以及端口（默认 5432).

  • 库贝内特斯： 端口转发Postgres服务，然后连接到 localhost 转发端口：

    kubectl port-forward -n <namespace> svc/<postgres-service> 5432:5432

    在另一个终端中，使用 POSTGRES_URL=postgres://USER:PASSWORD@localhost:5432/DATABASE.

使用任何数据库用户和密码；服务器不存储或修改凭据。

可选：限制表

集 ALLOWED_TABLES 以逗号分隔的表名列表来限制服务器可以访问的表。如果未设置，则允许数据库用户可见的所有表（受其权限限制）。

使用游标

  1. 打开 光标设置→ 特性→ MCP → 编辑配置 （或直接编辑MCP配置文件）。

    • macOS/Linux： ~/.cursor/mcp.json
    • 窗户： %USERPROFILE%\.cursor\mcp.json

  2. 添加Postgres MCP服务器。使用 绝对路径 到 postgres-mcp 二元的。路径 不得包含空格 （使用以下路径 ~/bin/postgres-mcp 或者，如果项目路径有空格，则使用符号链接）。

    {
  "mcpServers": {
    "postgres": {
      "command": "/absolute/path/to/postgres-mcp",
      "env": {
        "POSTGRES_URL": "postgres://USER:PASSWORD@HOST:PORT/DATABASE"
      }
    }
  }
}

  3. 保存文件并重新启动Cursor（或重新加载窗口）。

  4. 在聊天中，您可以要求AI列出表、描述模式、查询数据或运行工具公开的其他操作。人工智能将调用MCP工具；成功或失败取决于数据库用户的权限。

验证服务器

从终端运行服务器以确认其启动并连接：

export POSTGRES_URL="postgres://USER:PASSWORD@HOST:PORT/DATABASE"
./postgres-mcp

该进程将等待stdio上的输入（由MCP客户端使用）。在客户端连接之前，不会打印任何输出。按 Ctrl+C 停止。

工具参考

服务器公开了以下工具。每个操作都以配置的数据库用户身份执行；PostgreSQL强制执行特权。如果用户缺乏权限，操作将失败，并显示数据库错误。

数据（DML）

工具 描述 所需权限
list_tables 列出架构中的基表（默认值： public) 模式用法
describe_table 返回表的列名、数据类型和可空性 SELECT/information_schema
query_table 跑a SELECT 带可选列列表和限制（最多100行） SELECT
insert_table 插入一行；列和值（JSON数组） INSERT
update_table 更新与列=值匹配的行；设置列和值 更新
delete_table 删除与列=值匹配的行 删除

任意SQL

工具 描述 所需权限
run_sql 执行单个SQL语句（DDL或DML）。用于其他工具未涵盖的操作。 取决于陈述

表格（DDL）

工具 描述 所需权限
create_table 创建表格；列作为JSON数组 {name, type} 在架构上创建
drop_table 放下一张桌子（可选 CASCADE) 下降
alter_table_add_column ALTER TABLE ... ADD COLUMN 表上的ALTER
alter_table_drop_column ALTER TABLE ... DROP COLUMN 表上的ALTER
alter_table_rename_column ALTER TABLE ... RENAME COLUMN 表上的ALTER
alter_table_rename ALTER TABLE ... RENAME TO 表上的ALTER

索引

工具 描述 所需权限
create_index 创建索引（名称、表、列；可选UNIQUE） Create
drop_index 删除索引（可选 CASCADE) 下降

视图

工具 描述 所需权限
create_view 创建视图（架构、名称、SELECT查询） 在架构上创建
drop_view 删除视图（可选 CASCADE) 下降

函数

工具 描述 所需权限
create_function 创建或替换函数（模式、名称、参数、返回类型、语言、正文） Create on schema
drop_function 删除函数（模式、名称；重载解析的可选参数类型） Drop

触发器

工具 描述 所需权限
create_trigger 创建触发器（名称、表、BEFORE/AFTER、事件、函数名） 表上的触发器
drop_trigger 删除触发器（架构、触发器名称、表名称） Drop

模式

工具 描述 所需权限
create_schema 创建架构 Create
drop_schema 删除架构（可选 CASCADE) 下降

环境变量

变量 必填 描述
POSTGRES_URL 是* PostgreSQL连接URI。 或者， DATABASE_URL 被接受。
ALLOWED_TABLES 否 服务器可以访问的以逗号分隔的表名列表。如果未设置，则允许用户访问的所有表（仍受DB权限的约束）。

安全性和权限

  • 资格证书： 服务器仅使用连接字符串连接到PostgreSQL。它不会记录或转发凭据。集 POSTGRES_URL 在运行服务器的进程环境中（例如Cursor的MCP配置）。
  • 最小特权原则： 使用专用数据库用户，只授予您希望AI拥有的权限。对于只读使用，授予 CONNECT, USAGE，以及 SELECT；对于架构更改，请授予相应的权限 CREATE, ALTER, DROP 特权。
  • 表格列表： ALLOWED_TABLES 限制结构化工具的表（例如。 query_table, insert_table)可以瞄准。它不限制 run_sql；使用数据库权限来控制用户可以运行什么。
  • 单一声明： run_sql 每次调用执行一条语句。不支持对多个语句进行批处理。

代理商指南

如果使用此MCP的AI助手不断收到以下响应 SELECT 1 或 SELECT 42 它几乎总是调用 run_sql 阅读。该工具只返回PostgreSQL命令标签，不返回结果集。

有关AI使用说明，请参阅 MCP_AGENT_GUIDE.md. 使用 query_table （不是 run_sql)每当您需要实际的查询结果时。

许可证

这个项目是开源的。看 许可证 此存储库中的术语文件。

相关 MCP