Skip to main content
PostgreSQL MCP Pro Logo

中文 · English

PostgreSQL MCP Pro

索引调优 · 执行计划 · 健康检查 · 安全 SQL · 运维洞察

License: MIT PyPI GitHub Release GHCR

这是什么

PostgreSQL MCP Pro(CLI / PyPI:postgresql-mcp-pro)是面向 Cursor / Claude 等 MCP 客户端的 PostgreSQL 助手:能查 schema、跑只读 SQL、看执行计划、做健康检查、给索引建议,并补充表体积、冷索引、活动会话、阻塞等运维能力。

本仓库是 crystaldba/postgres-mcp 的维护型 fork:默认只读、修好上游依赖坑,并持续合入有价值的修复。

能力 说明
安全默认 默认 --access-mode=restricted(只读 + SQL 校验);写库需显式 unrestricted
依赖可用 pglast>=7.20,<8,避免上游 PyPI 旧版装不上
连接更稳 归还连接清理 session / HypoPG;stdio 孤儿进程会关池
运维工具 库总览、体积排行、重复/冷索引、autovacuum、活动会话、阻塞等

制品:

  • PyPI:pip / uvx postgresql-mcp-pro(推荐本机)
  • GitHub Release:wheel / sdist
  • GHCR:ghcr.io/poiig/postgresql-mcp-pro

怎么选接入方式

方式 适用 命令形态
A. uvx / 本地进程(stdio) 本机 Cursor,一人一库,最简单 uvx postgresql-mcp-pro
B. Docker(stdio) 不想装 Python,本机有 Docker docker run -i ...
C. HTTP(streamable-http) 远程 / 多人共用一个服务 常驻进程,客户端连 URL
SSE 旧客户端兼容 仍可用,优先用 C

本机日常开发推荐 A;集中部署推荐 C(并加 --stateless-http)。


A. 用 uvx(推荐本机)

先安装 uv,再在 Cursor mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": [
        "postgresql-mcp-pro",
        "--access-mode=restricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

需要写库时把 --access-mode=restricted 改成 --access-mode=unrestricted。

已克隆本仓库时:

uv sync
uv run postgresql-mcp-pro --access-mode=restricted

B. 用 Docker(stdio)

docker pull ghcr.io/poiig/postgresql-mcp-pro:latest

Cursor 配置:

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URI",
        "ghcr.io/poiig/postgresql-mcp-pro:latest",
        "--access-mode=restricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

容器内会把连接串里的 localhost 映射到宿主机(macOS/Windows:host.docker.internal)。

也可用密钥文件:

docker run -i --rm \
  -v /path/to/database-uri:/run/secrets/database-uri:ro \
  -e DATABASE_URI_FILE=/run/secrets/database-uri \
  ghcr.io/poiig/postgresql-mcp-pro:latest --access-mode=restricted

C. HTTP:streamable-http(推荐远程)

先在服务器启动(默认监听本机;对局域网开放时请自行加反代 / 鉴权 / TLS,不要裸奔公网):

docker run --rm -p 8000:8000 \
  -e DATABASE_URI=postgresql://username:password@host:5432/dbname \
  ghcr.io/poiig/postgresql-mcp-pro:latest \
  --access-mode=restricted \
  --transport=streamable-http \
  --stateless-http \
  --streamable-http-host=0.0.0.0 \
  --streamable-http-port=8000

本机开发也可用:

uv run postgresql-mcp-pro \
  --access-mode=restricted \
  --transport=streamable-http \
  --stateless-http \
  --streamable-http-host=127.0.0.1 \
  --streamable-http-port=8000

客户端连 http://<host>:8000/mcp(以实际 MCP 客户端要求为准)。

SSE(兼容)

uv run postgresql-mcp-pro --transport=sse --sse-host=0.0.0.0 --sse-port=8000

新部署优先 streamable-http + --stateless-http。


常用参数

uv run postgresql-mcp-pro --access-mode=unrestricted
uv run postgresql-mcp-pro --access-mode=restricted --max-rows=500

工具一览(节选)

工具 说明
list_schemas / list_objects / get_object_details 浏览 schema
execute_sql 执行 SQL(restricted 下只读校验)
explain_query 执行计划
analyze_db_health / analyze_query_indexes / analyze_workload_indexes 健康与索引
get_top_queries 慢查询(需 pg_stat_statements)
get_database_overview / list_table_sizes 库总览 / 体积
list_duplicate_indexes / list_index_usage 重复 / 冷索引
get_autovacuum_overview / get_table_bloat 清理与膨胀
list_qual_stats 谓词统计(需 pg_qualstats)
list_settings 关键参数白名单
list_active_queries / get_blocking_queries 活动会话 / 阻塞

建议扩展:pg_stat_statements、hypopg(索引推演)。


发布与版本

打 tag 触发 Release workflow:

git tag v1.0.0
git push origin v1.0.0

产出:

  • PyPI:postgresql-mcp-pro
  • GitHub Release:postgresql_mcp_pro-*.whl / .tar.gz
  • 镜像:ghcr.io/poiig/postgresql-mcp-pro:1.0.0 与 :latest

也可在 Actions 里用 workflow_dispatch 填版本号手动发版。


许可与上游

更细的英文说明见 README.en.md。

Metadata

Release files for postgresql-mcp-pro 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for postgresql-mcp-pro 1.0.0
File Size Uploaded Provenance Actions
postgresql_mcp_pro-1.0.0.tar.gz 253.0 kB With provenance Details for postgresql_mcp_pro-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for postgresql-mcp-pro 1.0.0
File Interpreter ABI Platform Actions
postgresql_mcp_pro-1.0.0-py3-none-any.whl Python 3 none any Details for postgresql_mcp_pro-1.0.0-py3-none-any.whl

Total release size: 346.5 kB

Release files / postgresql_mcp_pro-1.0.0.tar.gz

Download URL postgresql_mcp_pro-1.0.0.tar.gz
Size 253.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ed9544aba1af622ad01104ca8e4477409ac9c17eadbb68feefd2d53ec37abb9d
BLAKE2b-256 checksum
How to use checksums
a1197f6142255d7fa286d509979bc5c05bd21eaf9f105ecabf01542670932267
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / postgresql_mcp_pro-1.0.0-py3-none-any.whl

Download URL postgresql_mcp_pro-1.0.0-py3-none-any.whl
Size 93.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
28289e9d2643198a80922326a1e057f97cc3a2ddcf3a2c3475c9f90a73c7506c
BLAKE2b-256 checksum
How to use checksums
7fb964255d37e1fe3016df47945a246813fd37e1a7e007c2853fa4af4c2b5f30
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for postgresql-mcp-pro 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for postgresql_mcp_pro-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page