PostgreSQL Performance MCP

PostgreSQL Analyzer MCP

用于 PostgreSQL 数据库性能分析和优化的模型上下文协议（MCP）服务。

概述

PostgreSQL Analyzer MCP 是一款功能强大的工具，借助 AI 帮助数据库管理员和开发者优化 PostgreSQL 数据库。它可全面分析数据库结构、查询性能、索引使用情况和配置设置，并提供切实可行的改进建议。

此工具通过 Streamable HTTP 传输作为远程 MCP 服务运行，可集中部署，并由任何兼容 MCP 的客户端访问，包括 Amazon Q Developer CLI、Claude 以及其他支持 MCP 协议的 AI 助手。

⚠️ 免责声明

实验性项目：此项目处于实验阶段，旨在展示 MCP 与 PostgreSQL 的可能性。在任何生产环境中实施之前，都应仔细审核所有建议和代码。

非官方项目：这是一个个人项目，与我工作或参与的任何组织均无关联，也未获其认可，亦不代表其立场。所有观点和方法均为我个人所有。

不承担责任：此工具按“原样”提供，不附带任何形式的保证。使用风险由您自行承担。作者不对因使用此软件而产生的任何损害或问题承担责任。

功能

• 数据库结构分析：分析表、列、索引和外键
• 查询性能分析：分析执行计划并识别瓶颈
• 索引建议：根据查询模式获取新索引建议
• 查询优化：获取查询重写建议，以提升性能
• 慢查询识别：查找并分析运行缓慢的查询
• 数据库健康仪表板：全面了解数据库健康指标
• 索引使用情况分析：识别未使用、重复或臃肿的索引
• 只读查询执行：安全地执行只读查询以进行验证

安全性

此工具默认以只读模式运行。所有数据库连接都会执行 SET TRANSACTION READ ONLY，以防止意外修改数据库。查询执行功能严格限制为 SELECT、EXPLAIN 和 SHOW 命令。

安装

先决条件

• Python 3.12+（或 Docker）
• Amazon Aurora 或 RDS PostgreSQL 数据库
• AWS 账户（用于 Secrets Manager，可选）

设置

选项 1：本地设置

1. 克隆仓库：

   git clone https://github.com/yourusername/postgres-performance-mcp.git
   cd postgres-performance-mcp
   

2. 创建虚拟环境并安装依赖项：

   python -m venv venv
   source venv/bin/activate 
   pip install -r requirements.txt
   

选项 2：Docker 设置

1. 克隆仓库：

   git clone https://github.com/yourusername/postgres-performance-mcp.git
   cd postgres-performance-mcp
   

2. 构建 Docker 镜像：

   docker build -t postgres-analyzer-mcp -f Dockerfile .
   

3. 运行 Docker 容器：

   docker run -p 8000:8000 postgres-analyzer-mcp
   

   如需使用 AWS 凭证（使用 Secrets Manager 时）：

   docker run -p 8000:8000 \
     -e AWS_ACCESS_KEY_ID=your_access_key \
     -e AWS_SECRET_ACCESS_KEY=your_secret_key \
     -e AWS_DEFAULT_REGION=your_region \
     postgres-analyzer-mcp
   

4. 配置数据库凭证：

   • 选项 1：将凭证存储在 AWS Secrets Manager 中（推荐）
   • 选项 2：使用工具时直接提供凭证

使用方法

启动服务

本地：

python src/main.py --host 0.0.0.0 --port 8000

Docker：

# The server starts automatically when running the container
docker run -p 8000:8000 postgres-analyzer-mcp

配置 MCP 客户端

要连接到远程 MCP 服务，请按以下内容配置 MCP 客户端：

Server URL: http://your-server-address:8000/mcp
Transport: Streamable HTTP

与 MCP 客户端配合使用

使用任何兼容 MCP 的客户端连接到服务，并使用可用工具：

analyze_database_structure(secret_name="my-postgres-db-credentials", region_name="us-west-2")

可用工具

• analyze_database_structure：分析数据库架构并提供优化建议
• get_slow_queries：识别数据库中的慢查询
• analyze_query：分析 SQL 查询并提供优化建议
• recommend_indexes：为给定的 SQL 查询推荐索引
• suggest_query_rewrite：建议经过优化的 SQL 查询改写方案
• database_health_dashboard：生成全面的数据库健康状况仪表板
• query_optimization_wizard：通过交互式向导逐步优化 SQL 查询
• analyze_index_usage：分析索引使用模式，并识别未使用或效率低下的索引
• execute_read_only_query：执行只读 SQL 查询并返回结果
• show_postgresql_settings：显示 PostgreSQL 配置设置，可选择筛选条件
• health_check：检查服务是否正在运行且能正常响应

自定义

此工具的真正优势在于根据你的特定环境进行自定义：

• 根据数据库使用模式添加自定义分析规则
• 与监控系统集成
• 根据组织的最佳实践自定义建议
• 添加关于数据模型的领域专属知识
• 扩展符合你需求的其他工具

AWS Secrets Manager 设置

要使用 AWS Secrets Manager 存储数据库凭据：

1. 在 AWS Secrets Manager 中创建一个包含以下键的密钥：

   • host：数据库主机名
   • port：数据库端口（通常为 5432）
   • dbname：数据库名称
   • username：数据库用户名
   • password：数据库密码

2. 确保你的 AWS 凭据已配置适当的权限，以便访问该密钥。

3. 调用工具时使用密钥名称：

   analyze_query(query="SELECT * FROM users WHERE user_id = 123", secret_name="my-postgres-db-credentials")
   

PostgreSQL 配置

为获得最佳性能分析效果，我们建议启用以下扩展：

CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pg_buffercache;

并将以下设置添加到 postgresql.conf 中：

shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all

示例

分析数据库结构

analyze_database_structure(secret_name="my-postgres-db-credentials")

分析查询

analyze_query(
    query="SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE orders.status = 'pending'",
    secret_name="my-postgres-db-credentials"
)

获取索引建议

recommend_indexes(
    query="SELECT * FROM products WHERE category = 'electronics' AND price < 100",
    secret_name="my-postgres-db-credentials"
)

执行只读查询

execute_read_only_query(
    query="SELECT schemaname, relname, n_live_tup FROM pg_stat_user_tables ORDER BY n_live_tup DESC LIMIT 10",
    secret_name="my-postgres-db-credentials"
)

部署到远程服务

要将 MCP 服务部署到远程计算机：

1. 在远程服务上安装 Docker
2. 将项目文件复制到服务上，或从你的代码仓库克隆
3. 构建并运行 Docker 容器：

   docker build -t postgres-analyzer-mcp -f Dockerfile .
   docker run -d -p 8000:8000 postgres-analyzer-mcp
   

4. 考虑使用 docker-compose 或 systemd 等进程管理器，确保服务重启后容器也能重新启动

为确保安全访问，可考虑设置：

• 配置带 SSL/TLS 的反向代理（如 Nginx 或 Traefik）
• 身份验证中间件
• 限制访问的防火墙规则

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

• 感谢 PostgreSQL 社区提供文档
• 感谢 MCP 协议开发者打造 AI 驱动的工具
• 本项目采用 vibe coding（氛围编程）方式创建，这是一种 AI 辅助开发方法，结合人类专业知识与 AI 能力，打造稳健、易维护的软件解决方案。