这是什么
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 填版本号手动发版。
许可与上游
- 许可证:MIT
- 上游:crystaldba/postgres-mcp
- 本仓库:Poiig/postgresql-mcp-pro
更细的英文说明见 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.