pgtuner MCP

PostgreSQL性能调优MCP

](https://pypi.org/project/pgtuner-mcp/) ](https://pypi.org/project/pgtuner-mcp/)  ](https://pypi.org/project/pgtuner-mcp/) ](https://hub.docker.com/r/dog830228/pgtuner_mcp)

一个模型上下文协议（MCP）服务器，提供人工智能驱动的PostgreSQL性能调优功能。此服务器有助于识别慢速查询，推荐最佳索引，分析执行计划，并利用HypoPG进行假设索引测试。

特性

查询分析

• 从以下位置检索慢速查询 pg_stat_statements 有详细的统计数据
• 使用分析查询执行计划 EXPLAIN 和 EXPLAIN ANALYZE
• 通过自动化计划分析识别性能瓶颈
• 监控活动查询并检测长时间运行的事务

索引调整

• 基于查询工作量分析的人工智能索引推荐
• 假设指数测试 HypoPG 扩展（无磁盘使用）
• 查找未使用和重复的索引进行清理
• 创建前估计索引大小
• 在实施之前，使用建议的索引测试查询计划

数据库运行状况

• 通过多次检查进行综合健康评分
• 连接利用率监控
• 缓存命中率分析（缓冲区和索引）
• 锁争用检测
• 真空运行状况和事务ID环绕式监控
• 复制延迟监控
• 背景编写器和检查点分析

真空监测

• 实时跟踪长时间运行的VACUUM和VACUUM FULL操作
• 监控自动吸尘器的进度和性能
• 确定需要吸尘的桌子
• 查看最近的真空活动历史记录
• 分析自动真空配置的有效性

I/O性能分析

• 分析跨表和索引的磁盘读/写模式
• 识别I/O瓶颈和热表
• 监控缓冲区缓存命中率
• 跟踪指示work_mem问题的临时文件使用情况
• 分析检查点和后台写入程序I/O
• PostgreSQL 16+增强的pg_stat_io指标支持

配置分析

• 按类别查看PostgreSQL设置
• 获取内存、检查点、WAL、自动抽真空和连接设置的建议
• 识别次优配置

MCP提示和资源

• 用于常见调优工作流的预定义提示模板
• 用于表统计、索引信息和健康检查的动态资源
• 全面的文件资源

安装

标准安装（适用于Claude Desktop等MCP客户端）

pip install pgtuner_mcp

或使用 uv:

uv pip install pgtuner_mcp

手动安装

git clone https://github.com/isdaniel/pgtuner_mcp.git
cd pgtuner_mcp
pip install -e .

配置

环境变量

连接字符串格式： postgresql://user:password@host:port/database

最低用户权限

要运行此MCP服务器，PostgreSQL用户需要特定的权限来查询系统目录和扩展。以下是不同功能集所需的最小权限。

基本权限（核心功能所需）

-- Create a dedicated monitoring user
CREATE USER pgtuner_monitor WITH PASSWORD 'secure_password';

-- Grant connection to the target database
GRANT CONNECT ON DATABASE your_database TO pgtuner_monitor;

-- Grant usage on schemas
GRANT USAGE ON SCHEMA public TO pgtuner_monitor;
GRANT USAGE ON SCHEMA pg_catalog TO pgtuner_monitor;

-- Grant SELECT on user tables and indexes (for table stats and analysis)
GRANT SELECT ON ALL TABLES IN SCHEMA public TO pgtuner_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO pgtuner_monitor;

-- Grant access to system catalog views (read-only)
GRANT pg_read_all_stats TO pgtuner_monitor;  -- PostgreSQL 10+

扩展特定权限

对于pgstattuple（Bloat检测）：

-- Create the extension (requires superuser or appropriate privileges)
CREATE EXTENSION IF NOT EXISTS pgstattuple;

-- Grant execution on pgstattuple functions
GRANT EXECUTE ON FUNCTION pgstattuple(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstattuple_approx(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstatindex(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstatginindex(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstathashindex(regclass) TO pgtuner_monitor;

-- Alternative: Use pg_stat_scan_tables role (PostgreSQL 14+)
GRANT pg_stat_scan_tables TO pgtuner_monitor;

对于HypoPG（假设指数测试）：

-- Create the extension (requires superuser or appropriate privileges)
CREATE EXTENSION IF NOT EXISTS hypopg;

-- Grant SELECT on HypoPG views
GRANT SELECT ON hypopg_list_indexes TO pgtuner_monitor;
GRANT SELECT ON hypopg_hidden_indexes TO pgtuner_monitor;

-- Grant execution on HypoPG functions with proper signatures
GRANT EXECUTE ON FUNCTION hypopg_create_index(text) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_drop_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_reset() TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_hide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_unhide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_relation_size(oid) TO pgtuner_monitor;

-- Note: HypoPG operations are session-scoped and don't affect the actual database

完成安装脚本

-- 1. Create the monitoring user
CREATE USER pgtuner_monitor WITH PASSWORD 'secure_password';

-- 2. Grant connection and schema access
GRANT CONNECT ON DATABASE your_database TO pgtuner_monitor;
GRANT USAGE ON SCHEMA public TO pgtuner_monitor;

-- 3. Grant read access to user tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO pgtuner_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO pgtuner_monitor;

-- 4. Grant system statistics access
GRANT pg_read_all_stats TO pgtuner_monitor;  -- PostgreSQL 10+

-- Grant access to pg_stat_statements views explicitly
GRANT SELECT ON pg_stat_statements TO pgtuner_monitor;
GRANT SELECT ON pg_stat_statements_info TO pgtuner_monitor;

-- 5. Install and grant access to extensions (as superuser)
-- pg_stat_statements (required)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- pgstattuple (for bloat detection)
CREATE EXTENSION IF NOT EXISTS pgstattuple;
GRANT pg_stat_scan_tables TO pgtuner_monitor;  -- PostgreSQL 14+
-- OR grant individual functions:
-- GRANT EXECUTE ON FUNCTION pgstattuple(regclass) TO pgtuner_monitor;
-- GRANT EXECUTE ON FUNCTION pgstattuple_approx(regclass) TO pgtuner_monitor;
-- GRANT EXECUTE ON FUNCTION pgstatindex(regclass) TO pgtuner_monitor;

-- hypopg (for hypothetical index testing)
CREATE EXTENSION IF NOT EXISTS hypopg;
GRANT SELECT ON hypopg_list_indexes TO pgtuner_monitor;
GRANT SELECT ON hypopg_hidden_indexes TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_create_index(text) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_drop_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_reset() TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_hide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_unhide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_relation_size(oid) TO pgtuner_monitor;

-- 6. Verify permissions
SET ROLE pgtuner_monitor;
SELECT * FROM pg_stat_statements LIMIT 1;
SELECT * FROM pg_stat_activity WHERE pid = pg_backend_pid();
SELECT * FROM pgstattuple('pg_class') LIMIT 1;
SELECT * FROM hypopg_list_indexes();
RESET ROLE;

将特定用户排除在监控之外

您可以将特定的PostgreSQL用户排除在查询分析和监控结果之外。这有助于过滤：

• 监视或复制用户
• 系统帐户
• 内部应用程序服务帐户

设置 PGTUNER_EXCLUDE_USERIDS 带有逗号分隔的用户OID列表的环境变量：

# Exclude user IDs 16384, 16385, and 16386
export PGTUNER_EXCLUDE_USERIDS="16384,16385,16386"

要查找特定PostgreSQL用户的OID：

SELECT usesysid, usename FROM pg_user WHERE usename = 'monitoring_user';

配置后，将筛选以下查询：

• pg_stat_activity 查询（筛选 usesysid 列）
• pg_stat_statements 查询（筛选 userid 列）

这会影响以下工具 get_slow_queries, get_active_queries, analyze_wait_events, check_database_health，以及 get_index_recommendations.

MCP客户端配置

添加到您的 cline_mcp_settings.json 或Claude桌面配置：

{
  "mcpServers": {
    "pgtuner_mcp": {
      "command": "python",
      "args": ["-m", "pgtuner_mcp"],
      "env": {
        "DATABASE_URI": "postgresql://user:password@localhost:5432/mydb"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

或流式HTTP模式

{
  "mcpServers": {
    "pgtuner_mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

服务器模式

1.标准MCP模式（默认）

# Default mode (stdio)
python -m pgtuner_mcp

# Explicitly specify stdio mode
python -m pgtuner_mcp --mode stdio

2.HTTP SSE模式（传统Web应用程序）

SSE（服务器发送事件）模式为MCP通信提供了基于网络的传输。它对于需要基于HTTP通信的web应用程序和客户端非常有用。

# Start SSE server on default host/port (0.0.0.0:8080)
python -m pgtuner_mcp --mode sse

# Specify custom host and port
python -m pgtuner_mcp --mode sse --host localhost --port 3000

# Enable debug mode
python -m pgtuner_mcp --mode sse --debug

SSE端点：

SSE的MCP客户端配置：

对于支持SSE传输的MCP客户端（如Claude Desktop或自定义客户端）：

{
  "mcpServers": {
    "pgtuner_mcp": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

3.流式HTTP模式（现代MCP协议-推荐）

流式http模式实现了现代MCP流式http协议 /mcp 终点。它支持有状态（基于会话）和无状态模式。

# Start Streamable HTTP server in stateful mode (default)
python -m pgtuner_mcp --mode streamable-http

# Start in stateless mode (fresh transport per request)
python -m pgtuner_mcp --mode streamable-http --stateless

# Specify custom host and port
python -m pgtuner_mcp --mode streamable-http --host localhost --port 8080

# Enable debug mode
python -m pgtuner_mcp --mode streamable-http --debug

有状态vs无状态：

• 状态（默认）：使用以下命令跨请求维护会话状态 mcp-session-id 头球非常适合长时间交互。
• 无状态：为每个请求创建一个新的传输，不进行会话跟踪。非常适合无服务器部署或简单的请求/响应模式。

端点： http://{host}:{port}/mcp

可用工具

备注：所有工具都只关注用户/应用程序表和索引。系统目录表(pg_catalog, information_schema, pg_toast)自动从所有分析中排除。

性能分析工具

索引调整工具

数据库健康工具

Bloat检测工具（pgstattuple）

真空监测工具

刀具参数

get_slow查询

• limit：要返回的最大查询数（默认值：10）
• min_calls：最小呼叫计数筛选器（默认值：1）
• min_mean_time_ms：最小平均执行时间（毫秒）过滤器
• order_by：排序方式 mean_time, calls，或 rows

分析查询

• query （必填）：要分析的SQL查询
• analyze：使用EXPLAIN ANALYZE执行查询（默认值：true）
• buffers：包括缓冲区统计信息（默认值：true）
• format：输出格式- json, text, yaml, xml

get_index_推荐

• workload_queries：要分析的特定查询的可选列表
• max_recommendations：最大建议值（默认值：10）
• min_improvement_percent：最低改进阈值（默认值：10%）
• include_hypothetical_testing：使用HypoPG进行测试（默认值：true）
• target_tables：关注特定表格

检查_数据库_健康

• include_recommendations：包括可操作的建议（默认值：true）
• verbose：包括详细统计信息（默认值：false）

分析表

• table_name：要分析的特定表的名称（可选）
• schema_name：架构名称（默认值： public)
• use_approx：使用 pgstattuple_approx 为了更快地分析大型表（默认值：false）
• min_table_size_gb：要包含在架构范围扫描中的最小表大小（GB）（默认值：5）
• include_toast：包括TOAST表分析（默认值：false）

analyze_index_bloat

• index_name：要分析的特定索引的名称（可选）
• table_name：分析此表上的所有索引（可选）
• schema_name：架构名称（默认值： public)
• min_index_size_gb：要包含的最小索引大小（GB）（默认值：5）
• min_bloat_percent：仅显示膨胀超过此百分比的索引（默认值：20）

get_loat_summary

• schema_name：要分析的架构（默认值： public)
• top_n：要显示的顶部臃肿对象的数量（默认值：10）
• min_size_gb：要包含的最小对象大小（GB）（默认值：5）

监控_进度

• action：要执行的操作- progress （监测主动真空操作）， needs_vacuum （找到需要真空的桌子）， autovacuum_status （查看自动真空配置），或 recent_activity （查看最近的真空历史）
• schema_name：要分析的架构（默认值： public，与 needs_vacuum 行动）
• top_n：要返回的结果数（默认值：20）

分析disk_io模式

• analysis_type：I/O分析类型- all （全面）， buffer_pool （缓存命中率）， tables （表I/O模式）， indexes （索引I/O模式）， temp_files （临时文件使用），或 checkpoints （检查点I/O统计）
• schema_name：要分析的架构（默认值： public)
• top_n：要显示的顶级I/O密集型对象的数量（默认值：20）
• min_size_gb：要包含的最小对象大小（GB）（默认值：1）

MCP提示

服务器包括用于指导调优会话的预定义提示模板：

MCP资源

静态资源

• pgtuner://docs/tools -完整的工具文档
• pgtuner://docs/workflows -通用调优工作流程指南
• pgtuner://docs/prompts -提示模板文档

动态资源模板

• pgtuner://table/{schema}/{table_name}/stats -表格统计
• pgtuner://table/{schema}/{table_name}/indexes -表索引信息
• pgtuner://query/{query_hash}/stats -查询性能统计
• pgtuner://settings/{category} -PostgreSQL设置（内存、检查点、wal、自动抽真空、连接、所有）
• pgtuner://health/{check_type} -健康检查（连接、缓存、锁、复制、膨胀，所有）

PostgreSQL扩展设置

HypoPG扩展

HypoPG允许在不实际创建索引的情况下测试索引。这对于以下情况非常有用：

• 测试查询计划器是否会使用建议的索引
• 比较不同指标策略的执行计划
• 在提交之前估算存储需求

在数据库中启用HypoPG

HypoPG允许测试假设索引，而无需在磁盘上创建它们。

-- Create the extension
CREATE EXTENSION IF NOT EXISTS hypopg;

-- Verify installation
SELECT * FROM hypopg_list_indexes();

pg_stat_语句扩展

这 pg_stat_statements 扩展是 必需的 用于查询性能分析。它跟踪服务器执行的所有SQL语句的计划和执行统计信息。

步骤1：在postgresql.conf中启用扩展

将以下内容添加到您的 postgresql.conf 文件：

# Required: Load pg_stat_statements module
shared_preload_libraries = 'pg_stat_statements'

# Required: Enable query identifier computation
compute_query_id = on

# Maximum number of statements tracked (default: 5000)
pg_stat_statements.max = 10000

# Track all statements including nested ones (default: top)
# Options: top, all, none
pg_stat_statements.track = top

# Track utility commands like CREATE, ALTER, DROP (default: on)
pg_stat_statements.track_utility = on

备注：修改后 shared_preload_librariesPostgreSQL服务器 重新启动 是必需的。

步骤2：在数据库中创建扩展

-- Connect to your database and create the extension
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Verify installation
SELECT * FROM pg_stat_statements LIMIT 1;

pgstattuple扩展

这 pgstattuple 扩展是 必需的 用于膨胀检测工具(analyze_table_bloat, analyze_index_bloat, get_bloat_summary).它提供了获取表和索引的元组级统计信息的函数。

-- Create the extension
CREATE EXTENSION IF NOT EXISTS pgstattuple;

-- Verify installation
SELECT * FROM pgstattuple('pg_class') LIMIT 1;

性能影响考虑因素

小贴士：使用 pg_test_timing 在启用之前，测量特定系统的计时开销 track_io_timing.

示例用法

查找和分析慢速查询

# Get top 10 slowest queries
slow_queries = await get_slow_queries(limit=10, order_by="total_time")

# Analyze a specific query's execution plan
analysis = await analyze_query(
    query="SELECT * FROM orders WHERE user_id = 123",
    analyze=True,
    buffers=True
)

获取索引建议

# Analyze workload and get recommendations
recommendations = await get_index_recommendations(
    max_recommendations=5,
    min_improvement_percent=20,
    include_hypothetical_testing=True
)

# Recommendations include CREATE INDEX statements
for rec in recommendations["recommendations"]:
    print(rec["create_statement"])

数据库健康检查

# Run comprehensive health check
health = await check_database_health(
    include_recommendations=True,
    verbose=True
)

print(f"Health Score: {health['overall_score']}/100")
print(f"Status: {health['status']}")

# Review specific areas
for issue in health["issues"]:
    print(f"{issue}")

查找未使用的索引

# Find indexes that can be dropped
unused = await find_unused_indexes(
    schema_name="public",
    include_duplicates=True
)

# Get DROP statements
for stmt in unused["recommendations"]:
    print(stmt)

码头工人

docker pull  dog830228/pgtuner_mcp

# Streamable HTTP mode (recommended for web applications)
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode streamable-http

# Streamable HTTP stateless mode (for serverless)
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode streamable-http --stateless

# SSE mode (legacy web applications)
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode sse

# stdio mode (for MCP clients like Claude Desktop)
docker run -i \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode stdio

需求

• python: 3.10+
• PostgreSQL：12+（建议：14+）
• 扩展:

- pg_stat_statements （查询分析需要） - hypopg （可选，用于假设指数测试）

依赖项

核心依赖关系：

• mcp[cli]>=1.12.0 -模型上下文协议SDK
• psycopg[binary,pool]>=3.1.0 -带连接池的PostgreSQL适配器
• pglast>=7.10 -PostgreSQL查询解析器

可选（适用于HTTP模式）：

• starlette>=0.27.0 -ASGI框架
• uvicorn>=0.23.0 -ASGI服务器

贡献

欢迎投稿！请随时提交拉取请求。