Name: PostgreSQL数据库分析服务器
Author: blankbrackets

使用说明

Postgres MCP 服务器

一个基于TypeScript的模型上下文协议（MCP）服务器，为AI助手提供对PostgreSQL数据库的只读访问权限，以便进行全面分析和优化建议。

安装

NPM（推荐）

npm install -g blankbrackets-postgres-mcp-server

包裹；软件包：空白括号-postgres-mcp服务器

Docker

docker pull blankbrackets/postgres-mcp-server:latest

图像：空白括号/PostgreSQL-MCP服务器

来自源（或“来源”）

git clone https://github.com/blankbrackets/postgres-mcp.git
cd postgres-mcp
npm install && npm run build

特点/特性

🎯（瞄准、目标） 全面数据库分析 - 对整个数据库进行系统分析，并制定优先级行动计划
🔒（锁形符号，通常表示安全、保密或锁定状态） 设计为只读 - 多层保护确保数据不被修改
📊 表格/数据图表 10种专用工具 - 从表发现到查询性能分析
机器人🤖 AI优化过的 - 专为基于大型语言模型（LLM）的数据库优化而设计
📈 生产就绪 - 广泛的日志记录、错误处理和安全功能
⚡（闪电符号，常用于表示速度、能量或紧急情况） 快速性能 - 交互式使用中，工具执行时间低于50毫秒

它检测的内容

性能问题慢查询、缺失索引、过多的顺序扫描
索引问题未使用的索引、未索引的外键、重复的索引
模式问题数据类型不佳，空值率高，数据冗余
健康问题复制延迟，无效约束，序列接近最大值
维护需求需要执行VACUUM/ANALYZE的表，连接问题

快速入门

选项1：NPM（最简单）

全局安装已发布的包：

npm install -g blankbrackets-postgres-mcp-server

然后在Claude桌面版中进行配置：

{
  "mcpServers": {
    "postgres-analyzer": {
      "command": "blankbrackets-postgres-mcp-server",
      "env": {
        "DATABASE_URL": "postgresql://readonly_user:password@127.0.0.1:5432/your_db"
      }
    }
  }
}

重启Claude桌面版，开始分析！

选项2：Docker

# Build the image
docker build -t postgres-mcp-server .

# Run with your database
docker run -i \
  -e DATABASE_URL="postgresql://readonly_user:password@host.docker.internal:5432/your_db" \
  -v $(pwd)/logs:/app/logs \
  postgres-mcp-server

见 docs/DOCKER.md 如需详细的Docker操作指南。

选项3：从源（文件/位置）

# Clone the repository
git clone https://github.com/blankbrackets/postgres-mcp.git
cd postgres-mcp

# Install dependencies
npm install

# Build
npm run build

# Configure
cp env.example .env
# Edit .env with your DATABASE_URL

# Run
npm start

配置

环境变量：

DATABASE_URL=postgresql://readonly_user:password@127.0.0.1:5432/your_database
LOG_LEVEL=info              # Optional: error, warn, info, debug
QUERY_TIMEOUT=30000         # Optional: Query timeout in ms

与人工智能助手的集成

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json)：

使用NPM包 （建议在……之后 npm install -g blankbrackets-postgres-mcp-server):

{
  "mcpServers": {
    "postgres-analyzer": {
      "command": "blankbrackets-postgres-mcp-server",
      "env": {
        "DATABASE_URL": "postgresql://readonly_user:password@127.0.0.1:5432/your_database"
      }
    }
  }
}

使用本地构建 （用于开发）：

{
  "mcpServers": {
    "postgres-analyzer": {
      "command": "node",
      "args": ["/absolute/path/to/postgres-mcp/build/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://readonly_user:password@127.0.0.1:5432/your_database"
      }
    }
  }
}

见 examples/ 包含Cursor和Docker在内的更多配置示例。

4. 使用方法

重启您的MCP客户端（如Claude Desktop、Cursor等），并询问：

Do a comprehensive analysis and optimization of my database

人工智能将系统地分析您的数据库，并提供可操作的建议。

工具

🎯 目标/靶心 `comprehensive_database_analysis` - 从这里开始！

扫描 整个；全部 建立问题数据库，并制定完整的行动计划。

使用时机： “优化我的数据库”，“查找所有问题”，“完成分析”

返回值：

健康评分及关键问题总结
需要关注的表格优先级列表
逐步分析工作流程
快速见效与长期改进

⭐ `get_database_health` - 全面健康检查

数据库级指标与健康评估。

返回值：

缓存性能（命中率）
表统计信息（真空清理、分析、膨胀）
索引统计信息（未使用的索引）
连接利用率（活跃与闲置）
复制健康状态（延迟、槽位）
约束健康状况（无效约束）
序列健康状况（接近最大值警告）

📋（表格/清单） `list_tables` - 桌位发现

列出所有表，包括模式、类型、行数和大小。

使用前 任何用于获取确切表名的特定工具。

🔥 火焰、热情、活力等（根据上下文可具体翻译） `analyze_query_performance` - 查找慢查询

使用（某种方法/工具）识别最慢的查询 pg_stat_statements 或者使用 EXPLAIN 分析特定查询。

返回：

按执行时间排序的最慢N个查询
查询统计信息（调用次数、平均/最大时间、缓存命中率）
解释特定查询的计划
优化建议

注安装 pg_stat_statements 为获得最佳效果，请进行扩展。

📊 表格/数据图表 `get_query_statistics` - 表性能统计

对表格分析至关重要！ 为特定表提供详细的查询/输入/输出统计信息。

返回：

顺序扫描次数与索引扫描次数
缓存命中率（缓冲区缓存、索引缓存）
插入/更新/删除统计信息
按索引使用的统计信息
膨胀估计
上次真空处理/分析时间戳

🎯（瞄准目标） `suggest_indexing_strategies` - 索引优化

分析特定表的索引情况。

返回值：

索引使用统计
未使用的索引（从未被扫描过）
外键上缺少索引
重复/冗余索引
高顺序扫描警告

🏗️ 这个表情符号可以翻译为“建筑工地”或“正在建设中”，用来表示与建筑或施工相关的场景。 `suggest_schema_optimizations` - 模式设计

分析特定表的模式设计。

返回值：

列统计信息（可空性、基数、平均宽度）
外键分析（带索引与不带索引）
表膨胀指标
数据类型问题（低基数的TEXT类型，过大的VARCHAR类型）

📝 `get_table_info` - 表结构

返回表结构：列、数据类型、索引和约束。

⚠️（警告符号，无具体文字含义，通常用于提醒注意或警告） `execute_query` - 自定义SQL（最后手段）

执行自定义的只读SQL查询。

仅在……时使用 专用工具无法提供这些数据。

允许： SELECT（选择），WITH（使用），EXPLAIN（解释），SHOW（显示），TABLE（表），VALUES（值）
被阻止： 插入、更新、删除、丢弃（或“删除表”）、创建、修改，以及所有写操作

资源

`postgres://database/metadata`

包含所有模式、表、列、索引和约束的完整模式结构。

`postgres://system/catalog-reference`

PostgreSQL系统目录文档，用于防止常见查询错误。

使用前请阅读此内容 execute_query！

安全

只读强制执行

服务器是 设计为只读 具有多层保护层：

连接级别： default_transaction_read_only=on
SQL验证阻止写入关键字（INSERT、UPDATE、DELETE 等）
代码级别在任何工具中均未暴露写操作
数据库用户建议授予仅SELECT权限（见下文）

设置一个只读用户

-- Create read-only user
CREATE USER postgres_mcp_readonly WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE your_database TO postgres_mcp_readonly;
GRANT USAGE ON SCHEMA public TO postgres_mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO postgres_mcp_readonly;
GRANT pg_read_all_stats TO postgres_mcp_readonly;

看见 examples/setup-readonly-user.sql 以完成全部设置。

最佳实践

✅ 使用专用的只读数据库用户
✅ 永远不要提交（代码/更改等） .env 将文件纳入版本控制
✅ 在生产环境中使用SSL/TLS进行数据库连接
✅ 定期更换凭据
✅ 如有可能，通过IP限制数据库访问

示例提示

见 examples/example-prompts.md 以获取全面的示例。

推荐的工作流程：

1. "Do a comprehensive analysis and optimization of my database"
   → Creates complete action plan

2. "What are my slowest queries?"
   → Identifies performance bottlenecks

3. "List all tables"
   → Discovers database structure

4. "Analyze the [table_name] table"
   → Deep dive into specific tables

配置

环境变量

DATABASE_URL=postgresql://user:password@host:port/database  # Required
QUERY_TIMEOUT=30000      # Optional: Query timeout in ms (default: 30000)
LOG_LEVEL=info           # Optional: error, warn, info, debug (default: info)

记录（日志）

日志写入位置为：

文件: logs/postgres-mcp-server.log （以10MB为单位旋转，保留5个文件）
**标准错误输出（stderr）**被 Claude Desktop/Cursor 捕获用于调试

# View logs
tail -f logs/postgres-mcp-server.log

# Enable debug logging
# Add to config: "LOG_LEVEL": "debug"

发展

# Install dependencies
npm install

# Development mode (with auto-reload)
npm run dev

# Build for production
npm run build

# Run production build
npm start

# Clean build directory
npm run clean

建筑

TypeScript 与官方一起 @modelcontextprotocol/sdk
标准I/O传输 适用于Claude Desktop和Cursor的兼容性
PostgreSQL（中文常直接音译为“波斯特格瑞斯”或保持原英文名，因其是一个数据库管理系统名称，在中文语境中通常直接使用英文原名） 客户端通过 pg 图书馆
Winston日志记录 带有文件轮换功能
ES2022 模块 具有完全的类型安全性

看 docs/ARCHITECTURE.md 用于详细的架构文档。

故障排除

常见问题

服务器无法启动：

检查 DATABASE_URL 被设定
验证数据库是否可访问
查看日志： tail -f logs/postgres-mcp-server.log

工具执行失败：

使用 list_tables 首先发现确切的表名
检查 PostgreSQL 权限
阅读 postgres://system/catalog-reference 资源

大小写敏感错误：

PostgreSQL 对带引号的标识符区分大小写
使用来自（数据库/系统）的准确表名 list_tables
引用大小写混合的表格： "MyTable"

见 docs/TROUBLESHOOTING.md 以进行详细的故障排除。

它是如何工作的

连接以强制只读模式连接到 PostgreSQL
发现LLM（大型语言模型）使用 list_tables 查看可用的桌子
分析使用专用工具收集指标
建议大型语言模型（LLM）分析数据并提出优化建议

所有操作均为只读模式——数据库无法修改。

要求

Node.js18.0.0或更高版本
**PostgreSQL（译文保持原样，因为“PostgreSQL”是一个专有名词，通常不翻译，直接使用其英文原名）**9.6或以上
数据库访问读取权限（SELECT）

可选但建议：

pg_stat_statements 查询性能分析扩展

PostgreSQL 系统目录参考

服务器查询PostgreSQL系统表，例如：

information_schema.* - ANSI SQL 标准元数据
pg_stat_user_tables - 表统计
pg_stat_user_indexes - 索引使用
pg_indexes - 索引定义

重要视图之间的列名有所不同。请参阅 docs/POSTGRESQL_REFERENCE.md。

Docker 支持

使用 Docker

# Build
docker build -t postgres-mcp-server .

# Run
docker run -i \
  -e DATABASE_URL="postgresql://user:pass@host.docker.internal:5432/db" \
  postgres-mcp-server

使用 Docker Compose 配合使用

见 examples/docker-compose.yml：

docker-compose -f examples/docker-compose.yml up

Docker Hub ✅ 已发布

提供预构建的多架构镜像：

# Pull latest version
docker pull blankbrackets/postgres-mcp-server:latest

# Or specific version
docker pull blankbrackets/postgres-mcp-server:1.0.0

# Run directly
docker run -i \
  -e DATABASE_URL="postgresql://user:pass@host.docker.internal:5432/db" \
  blankbrackets/postgres-mcp-server:latest

支持的平台linux/amd64，linux/arm64

看 docs/DOCKER.md 以获取全面的 Docker 文档。

已发布的软件包 ✅

这台服务器可在以下位置使用：

✅ NPM 注册表 - blankbrackets-postgres-mcp-server (NPM视图)
✅ Docker Hub - blankbrackets/postgres-mcp-server (在Docker Hub上的查看)
✅（勾选符号，表示正确、确认或完成） GitHub - 源代码和发布版本（在GitHub上查看）

做出贡献

欢迎投稿！请参阅 docs/CONTRIBUTING.md 作为指南。

贡献领域

额外的分析工具
性能提升
更友好的错误提示
文档改进
错误修复
翻译
集成示例

许可证

MIT 许可证 - 详见许可证文件中详述。

支持

问题: GitHub Issues（GitHub问题）
讨论： GitHub 讨论区
日志检查 logs/postgres-mcp-server.log 用于调试
文档见 docs/ 文件夹

致谢

构建于：

模型上下文协议由Anthropic开发
PostgreSQL（译文保持原样，因为“PostgreSQL”是一个专有名词，通常不翻译）
Node.js 并且 TypeScript
温斯顿用于记录日志

使用说明

Postgres MCP 服务器

安装

NPM（推荐）

Docker

来自源（或“来源”）

特点/特性

它检测的内容

快速入门

选项1：NPM（最简单）

选项2：Docker

选项3：从源（文件/位置）

配置

与人工智能助手的集成

4. 使用方法

工具

🎯 目标/靶心 comprehensive_database_analysis - 从这里开始！

⭐ get_database_health - 全面健康检查

📋（表格/清单） list_tables - 桌位发现

🔥 火焰、热情、活力等（根据上下文可具体翻译） analyze_query_performance - 查找慢查询

📊 表格/数据图表 get_query_statistics - 表性能统计

🎯（瞄准目标） suggest_indexing_strategies - 索引优化

🏗️ 这个表情符号可以翻译为“建筑工地”或“正在建设中”，用来表示与建筑或施工相关的场景。 suggest_schema_optimizations - 模式设计

📝 get_table_info - 表结构

⚠️（警告符号，无具体文字含义，通常用于提醒注意或警告） execute_query - 自定义SQL（最后手段）

资源

postgres://database/metadata

postgres://system/catalog-reference

安全

只读强制执行

设置一个只读用户

最佳实践

示例提示

配置

环境变量

记录（日志）

发展

建筑

故障排除

常见问题

它是如何工作的

要求

PostgreSQL 系统目录参考

Docker 支持

使用 Docker

使用 Docker Compose 配合使用

Docker Hub ✅ 已发布

已发布的软件包 ✅

做出贡献

贡献领域

许可证

支持

致谢

相关项目

相关 MCP

PostgreSQL管理服务器

语言服务协议MCP

Postgres MCP Pro 数据库优化工具

PostgreSQL数据库交互服务

MCP长期记忆服务器

PostgreSQL只读查询服务

🎯 目标/靶心 `comprehensive_database_analysis` - 从这里开始！

⭐ `get_database_health` - 全面健康检查

📋（表格/清单） `list_tables` - 桌位发现

🔥 火焰、热情、活力等（根据上下文可具体翻译） `analyze_query_performance` - 查找慢查询

📊 表格/数据图表 `get_query_statistics` - 表性能统计

🎯（瞄准目标） `suggest_indexing_strategies` - 索引优化

🏗️ 这个表情符号可以翻译为“建筑工地”或“正在建设中”，用来表示与建筑或施工相关的场景。 `suggest_schema_optimizations` - 模式设计

📝 `get_table_info` - 表结构

⚠️（警告符号，无具体文字含义，通常用于提醒注意或警告） `execute_query` - 自定义SQL（最后手段）

`postgres://database/metadata`

`postgres://system/catalog-reference`