PostgreSQL MCP Server

postgres-mcp

PostgreSQL MCP 服务将模型上下文协议与安全的 PostgreSQL 沙盒相绑定。

具备 Code Mode——一种革命性方案，通过安全且真正的 V8 隔离环境（worker_threads）提供对全部 278 个工具的访问，消除多步工具调用造成的大量令牌开销。此外还支持架构内省、迁移跟踪、智能工具筛选、确定性错误处理、连接池、HTTP/SSE 传输、OAuth 2.1 身份验证，以及 citext、ltree、pgcrypto、pg_cron、pg_stat_kcache、pgvector、PostGIS 和 HypoPG 扩展。

278 个专用工具 · 24 个资源 · 21 个 AI 驱动的提示词

Docker Hub • npm 包 • MCP 注册表 • Wiki • 工具参考 • 变更日志

🎯 我们的优势

功能	描述
Code Mode（V8 Isolate）	大幅节省 Token： 在安全、真正的 V8 isolate（worker_threads）中执行复杂的多步骤操作。无需再为来回调用工具消耗 Token，AI 开销最多可降低 90%。
确定性错误处理	不再让晦涩难懂的数据库错误引发 AI 幻觉。我们会拦截原始 SQL 异常，并将其转换为清晰、可执行的建议，让 Agent 准确知道如何恢复，而不必猜测。
278 个 Token 优化工具	MCP registry 中规模最大的 PostgreSQL 工具集。每次查询都采用零成本 Token 估算和智能数据集截断，确保 Agent 始终掌握全局，同时避免超出上下文窗口。
OAuth 2.1 + 精细控制	真正的企业级安全。通过 OAuth 2.1 进行身份验证，并使用精确到具体工具层的权限范围，精准控制谁可以读取、写入或管理数据库。
审计跟踪与语义差异对比	全面可追溯。通过详细的 JSON 日志准确跟踪 AI 的操作，在变更前自动创建架构快照，并在恢复数据前可靠地审查逐行语义差异。
24 个资源与 21 个提示词	即时掌握数据库元信息。Agent 会自动读取实时健康状况、性能和复制指标，还能调用内置提示词工作流来优化查询和设计架构。
内省与迁移	防止代价高昂的错误。让 AI 模拟架构变更的级联影响，安全地安排外键更新顺序，并自动跟踪迁移历史。
8 个扩展生态系统	为高级工作负载做好准备。提供对 pgvector（AI 搜索）、PostGIS（地理空间）、pg_cron、pgcrypto 等的一级 API 支持，所有接口开箱即经过严格的类型检查和验证。
智能工具筛选	为 Agent 提供所需的一切，同时避免超出 IDE 限制。可动态编译服务，任意组合我们的 25 个不同工具组。
企业级基础设施	专为生产环境打造。速度极快（每秒数百万次操作）、可防范 SQL 注入、支持高性能连接池，并可同时支持 Streamable HTTP 和 Legacy SSE 协议。

建议规则（添加到 AGENTS.md、GEMINI.md 等文件中）

MCP Token 管理：

• Token 可见性：与 postgres-mcp 交互时，始终监控工具响应中返回的 _meta.tokenEstimate（或 Code Mode 中的 metrics.tokenEstimate）。
• 审计资源：使用 postgres://audit 资源查看会话级 Token 消耗情况，并识别高成本操作。
• 主动提升效率：如果操作消耗的 Token 较多，优先使用 code mode，并主动使用 limit 参数。

🚀 快速开始

前置条件

• PostgreSQL 12-18（已使用 PostgreSQL 18.1 测试）
• Docker（推荐）或 Node.js 24+（LTS）

Docker（推荐）

docker pull writenotenow/postgres-mcp:latest

添加到你的 ~/.cursor/mcp.json 或 Claude Desktop 配置中：

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "POSTGRES_HOST",
        "-e",
        "POSTGRES_PORT",
        "-e",
        "POSTGRES_USER",
        "-e",
        "POSTGRES_PASSWORD",
        "-e",
        "POSTGRES_DATABASE",
        "writenotenow/postgres-mcp:latest",
        "--tool-filter",
        "codemode",
        "--audit-log",
        "/tmp/postgres-logs/audit.jsonl"
      ],
      "env": {
        "POSTGRES_HOST": "host.docker.internal",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_DATABASE": "your_database"
      }
    }
  }
}

Docker 注意事项：使用 host.docker.internal 连接运行在主机上的 PostgreSQL。

📖 Docker 完整指南： DOCKER_README.md · Docker Hub

npm

npm install -g @neverinfamous/postgres-mcp
postgres-mcp --transport stdio --postgres postgres://user:password@localhost:5432/database

从源代码构建

git clone https://github.com/neverinfamous/postgres-mcp.git
cd postgres-mcp
npm install
npm run build
node dist/cli.js --transport stdio --postgres postgres://user:password@localhost:5432/database

开发

设置说明请参见上文的 从源代码构建。克隆后：

npm run lint && npm run typecheck  # Run checks
npm run bench                      # Run performance benchmarks
node dist/cli.js info              # Test CLI
node dist/cli.js list-tools        # List available tools

基准测试

运行 npm run bench，使用 Vitest Bench 执行性能基准测试套件（10 个文件，93+ 个场景）。使用 npm run bench:verbose 可查看详细表格输出。

性能亮点（Node.js 24，Windows 11）：

区域	基准测试	吞吐量
工具分发	Map.get() 单个工具查找	~6.9M ops/sec
WHERE 验证	简单子句（组合正则快速路径）	~3.7M ops/sec
标识符清理	validateIdentifier()	~4.4M ops/sec
身份验证 — 令牌提取	extractBearerToken()	~2.7M ops/sec
身份验证 — 作用域检查	hasScope()	~5.3M ops/sec
速率限制	单个 IP 检查	~2.3M ops/sec
日志记录器	经过筛选的调试（无操作路径）	~5.4M ops/sec
架构解析	MigrationInitSchema.parse()	~2.1M ops/sec
元数据缓存	缓存命中 + 未命中模式	~1.7M ops/sec
沙箱创建	CodeModeSandbox.create() 冷启动	~863 ops/sec

完整的基准测试结果和方法说明请参见 性能 Wiki 页面。

🔗 数据库连接场景

场景	使用的主机	示例连接字符串
主机上的 PostgreSQL	localhost 或 host.docker.internal	postgres://user:pass@localhost:5432/db
Docker 中的 PostgreSQL	容器名称或网络	postgres://user:pass@postgres-container:5432/db
远程/云端 PostgreSQL	主机名或 IP	postgres://user:[email protected]:5432/db

提供商	主机名示例
AWS RDS PostgreSQL	your-instance.xxxx.us-east-1.rds.amazonaws.com
Google Cloud SQL	project:region:instance（通过 Cloud SQL Proxy）
Azure PostgreSQL	your-server.postgres.database.azure.com
Supabase	db.xxxx.supabase.co
Neon	ep-xxx.us-east-1.aws.neon.tech

🛠️ 工具筛选

重要

默认情况下，所有工具组都包含 Code Mode（pg_execute_code）。如需排除它，请在筛选器中添加 -codemode：--tool-filter cron,pgcrypto,-codemode

💡 Code Mode（--tool-filter codemode）是推荐的配置 — 它会开放 pg_execute_code，这是一个安全、真正的 V8 isolate 沙箱，可提供全部 278 个工具的能力，最多可节省 90% 的 token。其他选项请参见工具筛选。

• 需要 admin OAuth 作用域 — 执行操作会记录以供审计

📖 查看完整安装指南 →

可以筛选什么？

--tool-filter 参数接受组或工具名称，可以自由组合：

筛选模式	示例	说明
仅使用组	core,jsonb,transactions	组合各个组
工具名称	pg_read_query,pg_explain	自定义工具选择
组 + 工具	core,+pg_stat_statements	扩展某个组
组 - 工具	core,-pg_drop_table	移除特定工具

工具组（共 25 个）

组	工具数	说明
codemode	1	Code Mode（沙盒化代码执行）🌟 推荐
core	21	读写查询、表、索引、便捷工具和删除工具
transactions	9	BEGIN、COMMIT、ROLLBACK、保存点、状态
jsonb	21	JSONB 操作、查询和美化输出
text	14	全文搜索、模糊匹配
performance	25	EXPLAIN、查询分析、优化、诊断、异常检测
admin	12	VACUUM、ANALYZE、REINDEX、洞察
monitoring	12	数据库大小、连接、状态
backup	13	pg_dump、COPY、恢复、备份审计
schema	13	架构、视图、序列、函数、触发器
introspection	7	依赖关系图、级联模拟、架构分析
migration	7	架构迁移跟踪与管理
partitioning	7	原生分区管理
stats	20	统计分析、窗口函数、异常值检测
vector	17	pgvector（AI/ML 相似性搜索）
postgis	16	PostGIS（地理空间）
cron	9	pg_cron（作业调度）
partman	11	pg_partman（自动分区）
kcache	8	pg_stat_kcache（操作系统级统计信息）
citext	7	citext（不区分大小写的文本）
ltree	9	ltree（层级数据）
pgcrypto	10	pgcrypto（加密、UUID）
security	10	安全审计、SSL、防火墙、数据脱敏、权限分析
roles	13	角色管理、权限、成员关系、RLS
docstore	10	JSONB 文档集合（NoSQL 风格的 CRUD、索引）

语法参考

前缀	目标	示例	效果
(none)	分组	core	**白名单模式：**仅启用此分组
(none)	工具	pg_read_query	**白名单模式：**仅启用此工具
+	分组	+vector	将此分组中的工具添加到当前集合
-	分组	-admin	从当前集合中移除此分组中的工具
+	工具	+pg_explain	添加一个指定工具
-	工具	-pg_drop_table	移除一个指定工具

🌐 HTTP/SSE 传输（远程访问）

如需远程访问、使用基于 Web 的客户端或兼容 HTTP 的 MCP 主机，请使用 HTTP 传输：

node dist/cli.js \
  --transport http \
  --port 3000 \
  --postgres "postgres://user:pass@localhost:5432/db"

Docker：

docker run --rm -p 3000:3000 \
  -e POSTGRES_URL=postgres://user:pass@host:5432/db \
  writenotenow/postgres-mcp:latest \
  --transport http --port 3000

该服务同时支持两种 MCP 传输协议，可让新旧客户端连接：

Streamable HTTP（推荐）

现代协议（MCP 2025-03-26）——单一端点，基于会话：

方法	端点	用途
POST	/mcp	JSON-RPC 请求（initialize、tools/list 等）
GET	/mcp	用于服务通知的 SSE 流
DELETE	/mcp	终止会话

会话通过 Mcp-Session-Id 标头进行管理。

无状态模式

适用于不需要会话的无服务器／无状态部署：

node dist/cli.js --transport http --port 3000 --stateless --postgres "postgres://..."

在无状态模式下：GET /mcp 返回 405，DELETE /mcp 返回 204，/sse 和 /messages 返回 404。每次 POST /mcp 都会创建一个新的传输实例。

旧版 SSE（向后兼容）

旧版协议（MCP 2024-11-05）——适用于 Python mcp.client.sse 等客户端：

方法	端点	用途
GET	/sse	打开 SSE 流，并返回 /messages?sessionId=<id> 端点
POST	/messages?sessionId=<id>	向会话发送 JSON-RPC 消息

实用端点

方法	端点	用途
GET	/health	健康检查（绕过速率限制，始终可供监控使用）

🔐 身份验证

postgres-mcp 的 HTTP 传输支持两种身份验证机制：

简单承载令牌（--auth-token）

适用于开发或单租户部署的轻量级身份验证：

node dist/cli.js --transport http --port 3000 --auth-token my-secret --postgres "postgres://..."

# Or via environment variable
export MCP_AUTH_TOKEN=my-secret
node dist/cli.js --transport http --port 3000 --postgres "postgres://..."

客户端必须在所有请求中包含 Authorization: Bearer my-secret。/health 和 / 除外。未经身份验证的请求会收到 401 响应，其中包含符合 RFC 6750 规范的 WWW-Authenticate: Bearer 标头。

OAuth 2.1（企业级）

符合 RFC 9728/8414 规范的完整 OAuth 2.1，适用于生产环境中的多租户部署：

node dist/cli.js \
  --transport http \
  --port 3000 \
  --postgres "postgres://user:pass@localhost:5432/db" \
  --oauth-enabled \
  --oauth-issuer http://localhost:8080/realms/postgres-mcp \
  --oauth-audience postgres-mcp-client

其他标志：--oauth-jwks-uri <url>（如未指定则自动发现）、--oauth-clock-tolerance <seconds>（默认值：60）。

OAuth 作用域

通过 OAuth 作用域管理访问控制：

作用域	访问级别
read	只读查询（SELECT、EXPLAIN）
write	读取和写入操作
admin	完整的管理权限
full	授予所有访问权限
db:{name}	访问指定数据库
schema:{name}	访问指定模式
table:{schema}:{table}	访问指定表

RFC 合规性

此实现遵循：

• RFC 9728 — OAuth 2.1 受保护资源元数据
• RFC 8414 — OAuth 2.1 授权服务器元数据
• RFC 7591 — OAuth 2.1 动态客户端注册

服务器会在 /.well-known/oauth-protected-resource 公开元数据。

Keycloak 用户请注意： 请为客户端添加 Audience mapper（Client → Client scopes → dedicated scope → Add mapper → Audience），以便在令牌中包含正确的 aud 声明。

说明

逐工具范围强制执行： 范围在工具级别强制执行——每个工具组都映射到一个必需范围（read、write 或 admin）。启用 OAuth 后，每次调用工具前都会检查调用方令牌的范围。未配置 OAuth 时，则完全跳过范围检查。

警告

HTTP 未启用身份验证： 使用 --transport http 而未启用 OAuth 或 --auth-token 时，所有客户端都拥有完全不受限制的访问权限。生产环境中的 HTTP 部署务必启用身份验证。详情请参阅 SECURITY.md。

优先级： 同时设置 --auth-token 和 --oauth-enabled 时，OAuth 2.1 优先。如果两者均未配置，服务器会发出警告并在未启用身份验证的情况下运行。

🔧 配置

环境变量

变量	默认值	描述	CLI 标志
POSTGRES_HOST	localhost	数据库主机	--host
POSTGRES_PORT	5432	数据库端口	--pg-port
POSTGRES_USER	postgres	数据库用户名	--user
POSTGRES_PASSWORD	(empty)	数据库密码	--password
POSTGRES_DATABASE	postgres	数据库名称	--database
POSTGRES_URL	—	连接字符串（优先于单独设置的变量）	--postgres
MCP_HOST	localhost	服务绑定主机（容器中使用 0.0.0.0）	--server-host
MCP_TRANSPORT	stdio	传输类型：stdio、http、sse	--transport
PORT	3000	http/sse 传输使用的 HTTP 端口	--port
MCP_AUTH_TOKEN	—	用于 HTTP 身份验证的简单 bearer 令牌	--auth-token
LOG_LEVEL	info	日志级别：debug、info、warning、error	--log-level
METADATA_CACHE_TTL_MS	30000	架构缓存 TTL（毫秒）	—
POSTGRES_TOOL_FILTER	—	工具筛选字符串（也可使用 MCP_TOOL_FILTER）	--tool-filter
MCP_RATE_LIMIT_MAX	100	每个 IP 在 15 分钟窗口内的速率限制	—
MCP_REQUEST_TIMEOUT	300000	用于防护 Slowloris 的 HTTP 请求超时（毫秒）	—
MCP_HEADERS_TIMEOUT	60000	HTTP 标头超时（毫秒）	—
TRUST_PROXY	false	信任 X-Forwarded-For 中的客户端 IP	--trust-proxy
OAUTH_ENABLED	false	启用 OAuth 2.1 身份验证	--oauth-enabled
OAUTH_ISSUER	—	授权服务器 URL	--oauth-issuer
OAUTH_AUDIENCE	—	预期的令牌受众	--oauth-audience
OAUTH_JWKS_URI	(auto)	JWKS URI（从 issuer 自动发现）	--oauth-jwks-uri
OAUTH_CLOCK_TOLERANCE	60	时钟容差（秒）	--oauth-clock-tolerance
AUDIT_LOG_PATH	—	审计日志文件路径（容器日志可设为 stderr）	--audit-log
AUDIT_REDACT	false	从审计条目中省略工具参数	--audit-redact
AUDIT_BACKUP	false	启用变更前的 DDL 快照	--audit-backup
AUDIT_BACKUP_DATA	false	在快照中包含示例数据行	--audit-backup-data
AUDIT_BACKUP_MAX_AGE	30	快照保留的最长时间（天）	--audit-backup-max-age
AUDIT_BACKUP_MAX_COUNT	1000	保留的快照数量上限	--audit-backup-max-count
AUDIT_BACKUP_MAX_DATA_SIZE	52428800	数据捕获的表大小上限（字节）	--audit-backup-max-data-size
AUDIT_READS	false	记录读取类工具调用（精简条目）	--audit-reads
AUDIT_LOG_MAX_SIZE	10485760	轮转前的日志文件大小上限（字节）。最多保留 5 个文件。	--audit-log-max-size

**别名：**也支持 PGHOST、PGPORT、PGUSER、PGPASSWORD、PGDATABASE（标准 PostgreSQL 客户端环境变量）。

**IAM 身份验证的连接池调优：**对于使用 IAM 身份验证的云托管数据库（例如 AWS RDS、Google Cloud SQL），请使用 --pool-max 控制连接池大小。

命令行参考

标志	描述
--postgres <url>	连接字符串
--host <host>	PostgreSQL 主机
--pg-port <port>	PostgreSQL 端口
--user <user>	用户名
--password <pw>	密码（建议使用 PGPASSWORD）
--database <db>	数据库名称
--ssl	启用 SSL
--pool-max <n>	最大连接池连接数（默认值：10）
--transport <type>	stdio | http | sse
--port <n>	HTTP 端口
--server-host <host>	服务绑定主机
--auth-token <token>	用于 HTTP 身份验证的简单持有者令牌
--stateless	无状态 HTTP 模式（无会话、无 SSE）
--tool-filter <filter>	工具筛选字符串
--log-level <level>	日志详细程度
--oauth-enabled	启用 OAuth 2.1
--trust-proxy	信任反向代理标头
--audit-log <path>	启用 JSONL 审计追踪（容器日志使用 stderr）
--audit-redact	从审计条目中省略工具参数
--audit-backup	启用变更前 DDL 快照
--audit-backup-data	在快照中包含示例数据行
--audit-backup-max-age <days>	快照最长保留天数（默认值：30）
--audit-backup-max-count <count>	保留的快照最大数量（默认值：1000）
--audit-backup-max-data-size <bytes>	数据采集的最大表大小（默认值：52428800）
--audit-reads	记录读取类工具调用（精简条目）
--audit-log-max-size <bytes>	日志轮转前的最大文件大小（默认值：10MB）。系统最多保留 5 个轮转后的历史存档，之后删除最旧的存档（.1 至 .5）。

🤖 AI 驱动的提示词

提示词可为复杂的数据库任务提供分步指导。无需费心判断要使用哪些工具以及使用顺序，只需调用提示词并遵循其工作流即可——非常适合学习 PostgreSQL 最佳实践或自动化重复性的 DBA 任务。

此服务包含 21 个智能提示词，用于引导工作流：

提示词	描述	所需组
pg_query_builder	使用 CTE 和窗口函数构建查询	core
pg_schema_design	设计包含约束和索引的架构	core
pg_performance_analysis	使用 EXPLAIN 分析并优化查询	core, performance
pg_migration	生成支持回滚的迁移脚本	core
pg_tool_index	延迟加载——所有工具的精简索引	—
pg_quick_query	常见操作的快速 SQL 查询指导	core
pg_quick_schema	探索数据库架构的快速参考	core
pg_database_health_check	全面的数据库健康状况评估	core, performance, monitoring
pg_backup_strategy	包含 RTO/RPO 的企业级备份规划	core, monitoring, backup
pg_index_tuning	索引分析与优化工作流	core, performance
pg_extension_setup	扩展安装与配置指南	core
pg_setup_pgvector	用于语义搜索的完整 pgvector 配置	core, vector
pg_setup_postgis	用于地理空间操作的完整 PostGIS 配置	core, postgis
pg_setup_pgcron	用于作业调度的完整 pg_cron 配置	core
pg_setup_partman	用于分区管理的完整 pg_partman 配置	core, partman
pg_setup_kcache	用于操作系统监控的完整 pg_stat_kcache 配置	core, kcache
pg_setup_citext	用于不区分大小写文本的完整 citext 配置	core, citext
pg_setup_ltree	用于层次结构数据的完整 ltree 配置	core, ltree
pg_setup_pgcrypto	用于加密函数的完整 pgcrypto 配置	core, pgcrypto
pg_safe_restore_workflow	使用 restoreAs 的 6 步安全恢复操作手册	backup
pg_setup_docstore	用于文档集合的完整 docstore 配置	core, docstore

📦 资源

资源无需编写查询，即可即时查看数据库状态。非常适合快速检查架构、运行状况或性能指标——AI 可以读取这些信息，在建议更改前了解数据库背景。

此服务提供 24 个资源，用于访问结构化数据：

资源	URI	描述
架构	postgres://schema	完整的数据库架构
表	postgres://tables	表列表及其大小
设置	postgres://settings	PostgreSQL 配置
统计信息	postgres://stats	数据库统计信息及过时检测
活动	postgres://activity	当前连接
连接池	postgres://pool	连接池状态
功能	postgres://capabilities	服务版本、扩展和工具类别
性能	postgres://performance	pg_stat_statements 查询指标
运行状况	postgres://health	全面的数据库运行状况
扩展	postgres://extensions	扩展清单及建议
索引	postgres://indexes	索引使用情况及未使用检测
复制	postgres://replication	复制状态和延迟监控
清理	postgres://vacuum	清理统计信息及事务 ID 回卷警告
锁	postgres://locks	锁争用检测
定时任务	postgres://cron	pg_cron 任务状态和执行历史
Partman	postgres://partman	pg_partman 分区配置和运行状况
Kcache	postgres://kcache	pg_stat_kcache CPU/I/O 指标摘要
向量	postgres://vector	pgvector 列、索引和建议
PostGIS	postgres://postgis	PostGIS 空间列和索引状态
加密	postgres://crypto	pgcrypto 可用性和安全建议
洞察	postgres://insights	AI 附加的业务洞察和观察结果
审计	postgres://audit	审计跟踪，含令牌摘要和常用工具
帮助	postgres://help/{group}	特定分组的帮助和工作流文档
文档存储	postgres://docstore	JSONB 文档集合概览

🔧 扩展支持

扩展	用途	工具
pg_stat_statements	查询性能跟踪	pg_stat_statements
pg_trgm	文本相似度	pg_trigram_similarity
fuzzystrmatch	模糊匹配	pg_fuzzy_match
hypopg	假设索引	pg_index_recommendations
pgvector	向量相似度搜索	16 个向量工具
PostGIS	地理空间操作	15 个 postgis 工具
pg_cron	任务调度	8 个 cron 工具
pg_partman	自动分区管理	10 个 partman 工具
pg_stat_kcache	操作系统级 CPU/内存/I/O 统计	7 个 kcache 工具
citext	不区分大小写的文本	6 个 citext 工具
ltree	层次树标签	8 个 ltree 工具
pgcrypto	哈希、加密、UUID	9 个 pgcrypto 工具

扩展工具会妥善处理扩展未安装的情况。扩展工具数量包含 create_extension 辅助工具，但不包含 Code Mode；上方的工具分组表格会为每个分组额外计入 +1 个 Code Mode 工具。

贡献

欢迎贡献！提交拉取请求前，请阅读我们的贡献指南。

安全

有关安全问题，请参阅我们的安全政策。

⚠️ 切勿提交凭据 - 请将密钥存储在环境变量中

许可证

本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

行为准则

参与本项目之前，请阅读我们的行为准则。