PostgreSQL performance Tuner MCP Server

PostgreSQL 性能调优 MCP

一个 Model Context Protocol (MCP) 服务，提供由 AI 驱动的 PostgreSQL 性能调优能力。此服务可帮助识别慢查询、推荐最佳索引、分析执行计划，并利用 HypoPG 测试假设索引。

功能

查询分析

• 从 pg_stat_statements 获取慢查询及其详细统计信息
• 使用 EXPLAIN 和 EXPLAIN ANALYZE 分析查询执行计划
• 通过自动化计划分析识别性能瓶颈
• 监控活动查询并检测长时间运行的事务

索引调优

• 根据查询工作负载分析，提供 AI 驱动的索引建议
• 使用 HypoPG 扩展测试假设索引（不占用磁盘空间）
• 查找未使用和重复的索引以便清理
• 在创建索引前估算其大小
• 在实施前，使用拟议的索引测试查询计划

数据库健康状况

• 通过多项检查进行全面的健康评分
• 监控连接利用率
• 分析缓存命中率（缓冲区和索引）
• 检测锁争用
• 监控 Vacuum 健康状况和事务 ID 回卷
• 监控复制延迟
• 分析后台写入器和检查点

Vacuum 监控

• 实时跟踪长时间运行的 VACUUM 和 VACUUM FULL 操作
• 监控自动清理的进度和性能
• 识别需要执行 vacuum 的表
• 查看近期 vacuum 活动历史
• 分析自动清理配置的有效性

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 .

配置

环境变量

变量	描述	必需
DATABASE_URI	PostgreSQL 连接字符串	是
PGTUNER_EXCLUDE_USERIDS	以逗号分隔的用户 ID（OID）列表；这些用户不会纳入监控	否
PGTUNER_STATEMENT_TIMEOUT_MS	每条语句的超时时间，单位为 ms（默认 30000，0=禁用）	否
PGTUNER_IDLE_TXN_TIMEOUT_MS	空闲事务超时时间，单位为 ms（默认 60000）	否
PGTUNER_LOCK_TIMEOUT_MS	锁超时时间，单位为 ms（默认 5000）	否
PGTUNER_CORS_ALLOW_ORIGINS	以逗号分隔的 CORS 允许列表；* 表示全部	否
PGTUNER_LINT_DISABLED_RULES	在检查器中禁用的规则 ID，以逗号分隔	否

连接字符串格式： 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（膨胀检测）：

-- 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 Desktop 配置中：

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

或使用 Streamable HTTP 模式

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

安全强化

pgtuner_mcp HTTP 模式（sse、streamable-http）不包含身份验证。仅在本地使用时安全；对于任何联网部署，必须在其前面设置一个负责处理身份验证和 TLS 的反向代理。

连接级防护（内置）

连接池启动的每个连接都会在握手时通过 libpq options 获得会话级防护：

环境变量	默认值	效果
PGTUNER_STATEMENT_TIMEOUT_MS	30000	每条语句的上限。限制 analyze_query 的 EXPLAIN ANALYZE。设为 0 可禁用。
PGTUNER_IDLE_TXN_TIMEOUT_MS	60000	终止遗留事务。设为 0 可禁用。
PGTUNER_LOCK_TIMEOUT_MS	5000	限制调优用户等待应用锁的时间。

双重保障——同时在监控角色上设置：

ALTER ROLE pgtuner_monitor SET statement_timeout = '30s';
ALTER ROLE pgtuner_monitor SET idle_in_transaction_session_timeout = '60s';

CORS

环境变量	默认值	效果
PGTUNER_CORS_ALLOW_ORIGINS	（默认：允许任意 localhost/127.0.0.1 端口，使用 http 或 https）	以逗号分隔的允许列表。设置此项会关闭 localhost 正则表达式默认规则，并改用字面来源匹配。使用 * 可允许所有来源（会强制 allow_credentials=false）。

推荐的反向代理模板（Caddy）

mcp.example.com {
  basicauth {
    teamuser <hashed_password>
  }
  reverse_proxy localhost:8080
}

未包含的功能

• 不提供 Bearer 令牌/API 密钥身份验证（由运维人员负责——请参阅反向代理）
• 不提供速率限制（由运维人员负责）
• 不提供进程内 TLS（请使用反向代理）
• 不提供按客户端设置的工具允许列表

服务模式

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 通信提供基于 Web 的传输方式。它适用于 Web 应用和需要基于 HTTP 通信的客户端。

# 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	GET	SSE 连接端点——客户端在此连接以接收服务端事件
/messages	POST	向服务端发送消息/请求

SSE MCP 客户端配置：

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

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

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

streamable-http 模式通过单个 /mcp 端点实现现代 MCP Streamable HTTP 协议。它同时支持有状态（基于会话）和无状态模式。

# 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

有状态与无状态：

• 有状态（默认）：使用 mcp-session-id 标头在请求之间保持会话状态。适用于长时间运行的交互。
• 无状态：每个请求都会创建新的传输，不跟踪会话。适用于无服务器部署或简单的请求/响应模式。

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

可用工具

注意：所有工具仅针对用户/应用表和索引。系统目录表（pg_catalog、information_schema、pg_toast）会自动从所有分析中排除。

性能分析工具

工具	描述
get_slow_queries	从 pg_stat_statements 获取慢查询及详细统计信息（总耗时、平均耗时、调用次数、缓存命中率）。排除系统目录查询。
analyze_query	使用 EXPLAIN ANALYZE 分析查询的执行计划，包括自动问题检测
get_table_stats	获取详细的表统计信息，包括大小、行数、死元组和访问模式
analyze_disk_io_patterns	分析磁盘 I/O 读写模式，识别热点表、缓冲区缓存效率和 I/O 瓶颈。支持按分析类型筛选（all、buffer_pool、tables、indexes、temp_files、checkpoints）。

索引调优工具

工具	描述
get_index_recommendations	基于查询工作负载分析的 AI 索引建议
explain_with_indexes	使用假设索引运行 EXPLAIN，在不创建真实索引的情况下测试改进效果
manage_hypothetical_indexes	创建、列出、删除或重置 HypoPG 假设索引。支持隐藏/取消隐藏现有索引。
find_unused_indexes	查找可安全删除的未使用索引和重复索引

数据库健康工具

工具	描述
check_database_health	全面的健康检查并提供评分（连接、缓存、锁、复制、事务回卷、磁盘、检查点）
get_active_queries	监控活动查询，查找长时间运行的事务和被阻塞的查询。默认排除系统进程。
analyze_wait_events	分析等待事件，以识别 I/O、锁或 CPU 瓶颈。重点关注客户端后端进程。
review_settings	按类别检查 PostgreSQL 设置并提供优化建议

膨胀检测工具（pgstattuple）

工具	描述
analyze_table_bloat	使用 pgstattuple 扩展分析表膨胀。显示死元组数量、可用空间和空间浪费百分比。
analyze_index_bloat	使用 pgstatindex 分析 B-tree 索引膨胀。显示叶节点密度、碎片情况以及空页/已删除页数量。也支持 GIN 和 Hash 索引。
get_bloat_summary	全面概览数据库膨胀情况，包括膨胀最严重的表/索引、可回收空间总量和优先维护操作。

Vacuum 监控工具

工具	描述
monitor_vacuum_progress	跟踪手动 VACUUM、VACUUM FULL 和自动清理操作。监控进度百分比、已回收的死元组数量、索引清理轮次和预计剩余时间。包括自动清理配置检查和需要维护的表。

工具参数

get_slow_queries

• limit：返回查询的最大数量（默认：10）
• min_calls：调用次数下限筛选值（默认：1）
• min_mean_time_ms：平均执行时间下限筛选值，单位为毫秒
• order_by：按 mean_time、calls 或 rows 排序

analyze_query

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

get_index_recommendations

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

check_database_health

• include_recommendations：包含可执行的建议（默认：true）
• verbose：包含详细统计信息（默认：false）

analyze_table_bloat

• table_name：要分析的特定表名（可选）
• schema_name：Schema 名称（默认：public）
• use_approx：在大型表上使用 pgstattuple_approx 以加快分析速度（默认：false）
• min_table_size_gb：在全 Schema 扫描中纳入的最小表大小，单位为 GB（默认：5）
• include_toast：包含 TOAST 表分析（默认：false）

analyze_index_bloat

• index_name：要分析的特定索引名称（可选）
• table_name：分析此表上的所有索引（可选）
• schema_name：Schema 名称（默认：public）
• min_index_size_gb：纳入分析的最小索引大小，单位为 GB（默认：5）
• min_bloat_percent：仅显示膨胀率高于此百分比的索引（默认：20）

get_bloat_summary

• schema_name：要分析的 Schema（默认：public）
• top_n：显示膨胀最严重的对象数量（默认：10）
• min_size_gb：纳入分析的最小对象大小，单位为 GB（默认：5）

monitor_vacuum_progress

• action：要执行的操作 - progress（监控正在进行的 vacuum 操作）、needs_vacuum（查找需要 vacuum 的表）、autovacuum_status（检查 autovacuum 配置）或 recent_activity（查看近期 vacuum 历史记录）
• schema_name：要分析的 Schema（默认：public，用于 needs_vacuum 操作）
• top_n：返回的结果数量（默认：20）

analyze_disk_io_patterns

• analysis_type：I/O 分析类型 - all（综合分析）、buffer_pool（缓存命中率）、tables（表 I/O 模式）、indexes（索引 I/O 模式）、temp_files（临时文件使用情况）或 checkpoints（检查点 I/O 统计信息）
• schema_name：要分析的 Schema（默认：public）
• top_n：显示 I/O 强度最高的对象数量（默认：20）
• min_size_gb：纳入分析的最小对象大小，单位为 GB（默认：1）

MCP 提示词

该服务包含用于引导调优会话的预定义提示词模板：

提示词	描述
diagnose_slow_queries	系统性慢查询排查工作流
index_optimization	全面分析并清理索引
health_check	全面评估数据库健康状况
query_tuning	优化特定 SQL 查询
performance_baseline	生成基准报告以供比较

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 设置（memory、checkpoint、wal、autovacuum、connections、all）
• pgtuner://health/{check_type} - 健康检查（connections、cache、locks、replication、bloat、all）

PostgreSQL 扩展设置

HypoPG 扩展

HypoPG 支持在不实际创建索引的情况下测试索引。这非常实用，可用于：

• 测试查询规划器是否会使用建议的索引
• 比较采用不同索引策略时的执行计划
• 在决定创建之前估算存储需求

在数据库中启用 HypoPG

HypoPG 支持测试假设索引，而无需在磁盘上创建索引。

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

-- Verify installation
SELECT * FROM hypopg_list_indexes();

pg_stat_statements 扩展

查询性能分析必须使用 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_libraries 后，必须重启 PostgreSQL 服务器。

步骤 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 扩展

膨胀检测工具（analyze_table_bloat、analyze_index_bloat、get_bloat_summary）必须使用 pgstattuple 扩展。它提供用于获取表和索引元组级统计信息的函数。

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

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

性能影响注意事项

设置	开销	建议
pg_stat_statements	低（约 1-2%）	始终启用
track_io_timing	低至中（约 2-5%）	在生产环境中启用，先进行测试
track_functions = all	低	对函数密集型工作负载启用
pg_stat_statements.track_planning	中	仅在调查规划问题时启用
log_min_duration_statement	低	建议用于识别慢查询

提示：启用 track_io_timing 前，请使用 pg_test_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

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 - Model Context Protocol SDK
• psycopg[binary,pool]>=3.1.0 - 支持连接池的 PostgreSQL 适配器
• pglast>=7.10 - PostgreSQL 查询解析器

可选（用于 HTTP 模式）：

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

集成测试

集成测试通过 Docker 对运行中的 PostgreSQL 执行每个 MCP 工具。

快速开始

make up PG=16            # start PG16 container
make test-integration    # run integration suite (defaults to PG=16)
make down                # tear down

支持的 PG 版本：14、15、16、17（例如：make up PG=17）。

CI 会通过 .github/workflows/integration.yml 在每个 PR 上针对全部四个 PG 版本运行测试套件。

贡献

欢迎贡献！欢迎提交 Pull Request。