License: MIT

mcp-postgres

用于 PostgreSQL 的 MCP 服务器。通过 Model Context Protocol 为 AI 智能体提供模式智能、查询执行和 DBA 工具。

与通用的数据库 MCP 服务器不同，mcp-postgres 是原生支持 Postgres 的。它提取表/列注释，理解 Postgres 特有的目录视图，提供索引分析，并附带可配置的访问级别，这样你就不会给 LLM 无限制的数据库访问权限。

功能特性

模式智能

列出模式、表、视图及其大小和行数
完整的表描述：列、类型、约束、索引、外键
提取 COMMENT ON 元数据 —— 为 LLM 提供关于列含义的语义上下文
在整个数据库中按名称或注释搜索对象

查询执行

具有自动行限制的只读 query 工具
受访问级别控制的可写 execute 工具
具有人类可读输出的 EXPLAIN ANALYZE

DBA 工具

表统计信息：活动/死元组、膨胀百分比、清理历史、扫描模式
索引分析：使用统计信息、未使用的索引检测、缺失索引建议
数据库健康状况：连接、缓存命中率、长时间运行的查询、吞吐量

安全性

四种访问级别：readonly、readwrite、admin、unrestricted
SQL 语句分类（SELECT、DML、DDL、admin）及强制执行
审计日志记录到 stderr（JSON 格式，每个查询一条记录）

快速开始

npx mcp-postgres --connection-string "postgres://user:pass@localhost:5432/mydb"

或者使用环境变量：

DATABASE_URL="postgres://user:pass@localhost:5432/mydb" npx mcp-postgres

Claude Desktop

添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-postgres",
        "--connection-string",
        "postgres://user:pass@localhost:5432/mydb"
      ]
    }
  }
}

Claude Code

添加到你项目的 .mcp.json 中：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "mcp-postgres"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
      }
    }
  }
}

工具

工具	描述	访问权限
`list_schemas`	列出带有表计数和大小的模式	readonly
`list_tables`	列出带有注释、行数、大小的表	readonly
`describe_table`	包含列、索引、外键、注释的完整表描述	readonly
`search_objects`	按名称或注释搜索对象	readonly
`query`	执行 SELECT 查询	readonly
`execute`	执行 INSERT/UPDATE/DELETE/CREATE 等	varies
`explain_query`	带有可读输出的 EXPLAIN (ANALYZE)	readonly*
`table_stats`	表统计信息、膨胀、清理信息	readonly
`index_analysis`	索引使用情况、未使用索引、缺失索引提示	readonly
`database_health`	连接、缓存比率、长查询、膨胀	readonly

*带有 analyze=true 的 explain_query 会执行查询，因此它遵循语句的访问级别。

资源

URI	描述
`postgres://schema/{name}`	模式的完整 DDL（带有注释的 CREATE TABLE 语句）
`postgres://extensions`	已安装的 PostgreSQL 扩展

提示词

提示词	描述
`explore-database`	指导性数据库探索 —— 模式、表、关系
`optimize-query`	使用 EXPLAIN、索引和建议分析慢查询
`health-check`	全面的数据库健康评估

配置

CLI 选项

--connection-string  PostgreSQL connection URL
--access-level       readonly|readwrite|admin|unrestricted (default: readonly)
--row-limit          Max rows returned per query (default: 500)
--schema             Default schema filter (default: public)
--audit              Enable query audit logging to stderr

环境变量

变量	描述
`DATABASE_URL`	PostgreSQL 连接 URL
`POSTGRES_URL`	备用连接 URL
`MCP_POSTGRES_ACCESS_LEVEL`	访问级别覆盖
`MCP_POSTGRES_ROW_LIMIT`	行数限制覆盖

访问级别

级别	SELECT	INSERT/UPDATE/DELETE	CREATE/ALTER/DROP	TRUNCATE/DROP DATABASE
`readonly`	是	否	否	否
`readwrite`	是	是	否	否
`admin`	是	是	是	否
`unrestricted`	是	是	是	是

默认为 readonly。请使用所需的最低级别。

审计日志

使用 --audit 启用。将每个工具调用记录到 stderr 作为 JSON：

{"timestamp":"2026-04-03T12:00:00.000Z","tool":"query","sql":"SELECT * FROM users","statementType":"select","accessLevel":"readonly","allowed":true,"durationMs":12,"rowCount":42}

将 stderr 管道传输到文件以进行捕获：mcp-postgres --audit 2>audit.log

架构

src/
├── index.ts             Entry point and CLI
├── server.ts            MCP server setup
├── config.ts            Configuration parsing
├── db/
│   ├── pool.ts          Connection pool management
│   └── query.ts         Query execution with timing
├── tools/
│   ├── schema.ts        Schema exploration tools
│   ├── query.ts         Query execution tools
│   └── performance.ts   DBA and health tools
├── resources/
│   └── schema.ts        Schema DDL resources
├── prompts/
│   └── index.ts         Prompt templates
└── safety/
    ├── classifier.ts    SQL statement classification
    ├── access.ts        Access level enforcement
    └── audit.ts         Audit logging

开发

npm install
npm test           # run tests
npm run build      # compile TypeScript
npm run dev -- --connection-string "postgres://..."  # run in dev mode

许可证

MIT

mcp-postgres

mcp-postgres

功能特性

快速开始

Claude Desktop

Claude Code

工具

资源

提示词

配置

CLI 选项

环境变量

访问级别

审计日志

架构

开发

许可证

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API