MCP PostgreSQL Operations

用于PostgreSQL操作和监控的MCP服务器




______________________________________________________________________

建筑与内部（DeepWiki）


______________________________________________________________________

概述

MCP PostgreSQL操作 是一个用于PostgreSQL数据库操作、监控和管理的专业MCP服务器。支持PostgreSQL 12-18，通过自然语言查询提供全面的数据库分析、性能监控和智能维护建议。大多数功能独立工作，但高级查询分析功能在以下情况下得到了增强 pg_stat_statements 以及（可选） pg_stat_monitor 扩展已安装。

______________________________________________________________________

特性

• ✅ 零配置：与PostgreSQL 12-18配合使用，开箱即用，具有自动版本检测功能。
• ✅ 自然语言：问“显示慢速查询”或“分析表膨胀”之类的问题
• ✅ 安全生产：只读操作，RDS/Aurora兼容常规用户权限。
• ✅ 扩展增强：可选 pg_stat_statements 和 pg_stat_monitor 用于高级查询分析。
• ✅ 全面的数据库监控：性能分析、膨胀检测和维护建议。
• ✅ 智能查询分析：查询识别速度较慢 pg_stat_statements 和 pg_stat_monitor 整合。
• ✅ 模式和关系发现：使用详细的关系映射进行数据库结构探索。
• ✅ 真空与自动真空智能：实时维护监控和有效性分析。
• ✅ 多数据库操作：无缝的跨数据库分析和监测。
• ✅ 企业就绪：具有RDS/Aurora兼容性的安全只读操作。
• ✅ 开发者友好：简单的代码库，便于定制和工具扩展。

🔧 高性能

• 版本感知I/O统计（在PostgreSQL 16+上增强，在PG 18+上增强字节列）。
• 实时连接和锁监控。
• 后台流程和检查点分析。
• 复制状态和WAL监控。
• 数据库容量和膨胀分析。
• 等待带有描述的事件目录（PG 17+）。
• WAL汇总器监控增量备份（PG 17+）。
• 异步I/O子系统监控（PG 18+）。
• 根据后端I/O和WAL统计数据（PG 18+）。

工具使用示例

📸 更多截图示例→

______________________________________________________________________

MCP-PostgreSQL-Ops Usage Screenshot

______________________________________________________________________

MCP-PostgreSQL-Ops Usage Screenshot

______________________________________________________________________

⭐ 快速入门（5分钟）

注： 这 postgresql 集装箱包含在 docker-compose.yml 仅用于快速入门测试目的。您可以通过根据需要调整环境变量来连接到自己的PostgreSQL实例。

如果你想使用自己的PostgreSQL实例而不是内置的测试容器： - 在您的数据库中更新目标PostgreSQL连接信息 .env 文件（请参见POSTGRES_HOST、POSTGRES_PORT、POSTGRESS_USER、POTGRES_PASSWORD、POSTGRES_DB）。 - 在 docker-compose.yml，注释掉（禁用） postgres 和 postgres-init-extensions 容器，以避免启动内置测试数据库。

快速入门/教程流程图

Flow Diagram of Quickstart/Tutorial

1.环境设置

备注：虽然超级用户权限提供对所有数据库和系统信息的访问，但MCP服务器也可以使用常规用户权限进行基本监控任务。

git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

### Check and modify .env file
cp .env.example .env
vim .env

### No need to modify defaults, but if using your own PostgreSQL server, edit below:
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432  # External port for host access (mapped to internal 5432)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # Default connection DB. Superusers can access all DBs.

备注: PGDATA=/data/db 为Percona PostgreSQL Docker镜像预配置，这需要此特定路径才能获得适当的写入权限。

2.启动演示容器

# Start all containers including built-in PostgreSQL for testing
docker-compose up -d

# Alternative: If using your own PostgreSQL instance
# Comment out postgres and postgres-init-extensions services in docker-compose.yml
# Then use the custom configuration:
# docker-compose -f docker-compose.custom-db.yml up -d

⏰ 等待环境设置：由于容器按顺序启动，初始环境设置需要几分钟的时间： 1. PostgreSQL 容器首先从数据库初始化开始 1. PostgreSQL扩展 容器安装扩展并创建全面的测试数据（约83K条记录） 1. MCP服务器 和 MCPO代理 容器在PostgreSQL准备就绪后启动 1. OpenWeb用户界面 容器最后启动，可能需要额外的时间来加载web界面 💡 小贴士：跑步后等待2-3分钟 docker-compose up -d 在访问OpenWebUI之前，确保所有服务都已完全初始化。

🔍 检查集装箱状态 （可选）：

# Monitor container startup progress
docker-compose logs -f

# Check if all containers are running
docker-compose ps

# Verify PostgreSQL is ready
docker-compose logs postgres | grep "ready to accept connections"

3.访问OpenWebUI

http://localhost:3003/

• MCP工具功能列表由提供 swagger 可在MCPO API文档URL中找到。

- 例如： http://localhost:8003/docs

4.在OpenWebUI中注册该工具

📌 备注：Web UI配置说明基于OpenWebUI v0.6.22。菜单位置和设置在较新版本中可能有所不同。

1. 使用管理员帐户登录OpenWebUI
2. 转到“设置”→ 顶部菜单中的“工具”。
3. 输入 postgresql-ops 工具地址（例如。， http://localhost:8003/postgresql-ops)连接MCP工具。
4. 设置Ollama或OpenAI。

5.完成！

祝贺 您的MCP PostgreSQL操作服务器现在可以使用了。您可以开始使用自然语言查询来探索您的数据库。

🚀 尝试以下示例查询：

• “显示当前活动的连接”
• “系统中最慢的查询是什么？”
• “分析所有数据库中的表膨胀”
• “显示数据库大小信息”
• “哪些桌子需要真空维护？”

📖 下一步：

• 浏览 查询示例部分 下面是更多查询示例
• 结账 带有截图的工具使用示例 用于视觉引导
• 探索 工具兼容性矩阵 了解可用功能

______________________________________________________________________

（注）样品测试数据概述

这 create-test-data.sql 脚本由执行 postgres-init-extensions 容器（在docker compose.yml中定义）在首次启动时自动生成用于MCP工具测试的全面测试数据库：

已创建测试用户： app_readonly, app_readwrite, analytics_user, backup_user

针对测试进行了优化： 有意的表膨胀、各种索引（已使用/未使用）、时间序列数据、复杂的关系

______________________________________________________________________

工具兼容性矩阵

自动适应： 所有工具在支持的版本之间透明地工作，无需配置！

🟢 独立于扩展的工具（不需要扩展）

🚀 版本感知工具（自动适应）

🟡 扩展依赖工具（需要扩展）

🆕 版本特定功能

PostgreSQL 17

• pg_wait_events 视图：带有描述的本机等待事件目录（由使用 get_wait_events)
• WAL汇总器：监控增量备份支持（由使用 get_wal_summarizer_status)
• 复制槽增强功能: invalidation_reason 和 inactive_since 列（由使用 get_replication_status)
• pg_stat_statements stats_since：跟踪上次重置统计信息的时间（由使用 get_pg_stat_statements_top_queries)
• 真空进度：索引真空跟踪进展视图（未来增强 get_running_vacuum_operations)

PostgreSQL 18

• pg_aios 视图：异步I/O子系统监控（由 get_async_io_status)
• 根据后端I/O统计数据：单个后端I/O和WAL统计数据（由使用 get_per_backend_io_stats)
• 真空/分析时间列: total_vacuum_time, total_autovacuum_time, total_analyze_time, total_autoanalyze_time 累积计时（由 get_vacuum_analyze_stats)
• pg_stat_io 字节列: read_bytes, write_bytes, extend_bytes （使用人 get_io_stats)
• 平行工作者统计数据: parallel_workers_launched, parallel_workers_to_launch （使用人 get_database_stats)
• 检查点增强功能: num_done, slru_written 列（由使用 get_bgwriter_stats)

______________________________________________________________________

用法示例

Claude桌面集成

（推荐）添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

“以清晰易读的html表格格式显示所有活动连接。” Claude Desktop Integration

“以美人鱼图的形式显示电子商务数据库中客户表的所有关系。” Claude Desktop Integration

______________________________________________________________________

安装

来自PyPI（推荐）

# Install the package
pip install mcp-postgresql-ops

# Or with uv (faster)
uv add mcp-postgresql-ops

# Verify installation
mcp-postgresql-ops --help

源自

# Clone the repository
git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

# Install with uv (recommended)
uv sync
uv run mcp-postgresql-ops --help

# Or with pip
pip install -e .
mcp-postgresql-ops --help

______________________________________________________________________

MCP配置

Claude桌面配置

（可选）使用本地源运行：

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_postgresql_ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

以标准模式运行MCP服务器

/w Pypi和uvx（推荐）

# Stdio mode
uvx --python 3.12 mcp-postgresql-ops \
  --type stdio

# HTTP mode
uvx --python 3.12 mcp-postgresql-ops
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

（选项）配置多个PostgreSQL实例

{
  "mcpServers": {
    "Postgresql-A": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "a.foo.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    },
    "Postgresql-B": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "b.bar.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    }
  }
}

/w本地来源

# Method 1: Module execution (for development, requires PYTHONPATH)
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops \
  --type stdio

# Method 2: Direct script (after uv installation in project directory)
uv run mcp-postgresql-ops \
  --type stdio

# Method 3: Installed package script (after pip/uv install)
mcp-postgresql-ops \
  --type stdio

# HTTP mode examples:
# Development mode
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

# Production mode (after installation)
mcp-postgresql-ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

______________________________________________________________________

CLI参数

• --type：运输类型(stdio 或 streamable-http)-默认值： stdio
• --host：HTTP传输的主机地址-默认值： 127.0.0.1
• --port：HTTP传输的端口号-默认值： 8000
• --auth-enable：为可流式传输的http模式启用承载令牌身份验证-默认值： false
• --secret-key：承载令牌身份验证的密钥（启用身份验证时需要）
• --log-level：日志记录级别（调试、信息、警告、错误、严重）-默认值： INFO

______________________________________________________________________

环境变量

备注: POSTGRES_DB 当没有指定特定数据库时，用作操作的默认目标数据库。在Docker环境中，如果设置为非默认名称，则此数据库将在PostgreSQL初始启动时自动创建。

端口配置：内置的PostgreSQL容器使用端口映射 15432:5432 哪里：

• POSTGRES_PORT=15432：用于主机访问和MCP服务器连接的外部端口
• DOCKER_INTERNAL_PORT_POSTGRESQL=5432：内部容器端口（PostgreSQL默认）
• 使用外部PostgreSQL服务器时，设置 POSTGRES_PORT 以匹配服务器的实际端口

______________________________________________________________________

先决条件

必需的PostgreSQL扩展

有关更多详细信息，请参阅 ##工具兼容性矩阵

备注：大多数MCP工具在没有任何PostgreSQL扩展的情况下工作。下面的部分。一些高级性能分析工具需要以下扩展：

-- Query performance statistics (required only for get_pg_stat_statements_top_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Advanced monitoring (optional, used by get_pg_stat_monitor_recent_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;

快速设置：对于新的PostgreSQL安装，请添加到 postgresql.conf:

shared_preload_libraries = 'pg_stat_statements'

然后重新启动PostgreSQL并运行上面的CREATE EXTENSION命令。

• pg_stat_statements 仅适用于慢速查询分析工具。
• pg_stat_monitor 是可选的，用于实时查询监控。
• 所有其他工具都可以在没有这些扩展的情况下工作。

最低要求

• PostgreSQL 12+（用PostgreSQL 17和18测试）
• Python 3.12
• PostgreSQL服务器的网络访问
• 读取系统目录的权限

所需的PostgreSQL配置

⚠️ 统计数据收集设置: 一些MCP工具需要特定的PostgreSQL配置参数来收集统计数据。选择以下配置方法之一：

受这些设置影响的工具:

• get_user_functions_status：需要 track_functions = pl 或 track_functions = all
• get_table_io_tasts & get_index_io_tasts：更精确的计时 track_io_timing = on
• get_database_stats：通过以下方式增强I/O时序 track_io_timing = on

验证: 应用任何方法后，验证设置：

SELECT name, setting, context FROM pg_settings WHERE name IN ('track_activities', 'track_counts', 'track_io_timing', 'track_functions') ORDER BY name;

       name       | setting |  context  
------------------+---------+-----------
 track_activities | on      | superuser
 track_counts     | on      | superuser
 track_functions  | pl      | superuser
 track_io_timing  | on      | superuser
(4 rows)

方法1:postgresql.conf（推荐用于自管理postgresql）

将以下内容添加到您的 postgresql.conf:

# Basic statistics collection (usually enabled by default)
track_activities = on
track_counts = on

# Required for function statistics tools
track_functions = pl    # Enables PL/pgSQL function statistics collection

# Optional but recommended for accurate I/O timing
track_io_timing = on    # Enables I/O timing statistics collection

然后重新启动PostgreSQL服务器。

方法2:PostgreSQL启动参数

对于Docker或命令行PostgreSQL启动：

# Docker example
docker run -d \
  -e POSTGRES_PASSWORD=mypassword \
  postgres:17 \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

# Direct postgres command
postgres -D /data \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

方法3：动态配置（AWS RDS、Azure、GCP、托管服务）

对于无法修改的托管PostgreSQL服务 postgresql.conf，使用SQL命令动态更改设置：

-- Enable basic statistics collection (usually enabled by default)
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';

-- Enable function statistics collection (requires superuser privileges)
ALTER SYSTEM SET track_functions = 'pl';

-- Enable I/O timing statistics (optional but recommended)
ALTER SYSTEM SET track_io_timing = 'on';

-- Reload configuration without restart (run separately)
SELECT pg_reload_conf();

会话级测试的替代方案:

-- Set for current session only (temporary)
SET track_activities = 'on';
SET track_counts = 'on';
SET track_functions = 'pl';
SET track_io_timing = 'on';

备注：使用命令行工具时，分别运行每个SQL语句以避免事务块错误。

______________________________________________________________________

RDS/Aurora兼容性

• 此服务器是只读的，可以在RDS/Aurora上使用常规角色。对于高级分析，启用pg_stat_语句；pg_stat_monitor在托管引擎上不可用。
• 在RDS/Aurora上，对于持久设置，首选DB参数组而不是ALTER SYSTEM。

  -- Verify preload setting
  SHOW shared_preload_libraries;

  -- Enable extension in target DB
  CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

  -- Recommended visibility for monitoring
  GRANT pg_read_all_stats TO ;

______________________________________________________________________

查询示例

🟢 独立于扩展的工具（始终可用）

• get_server_info

- “显示PostgreSQL服务器版本和扩展状态。” - “检查是否安装了pg_stat_语句。”

• get_active_connections

- “显示所有活动连接。” - “列出当前与数据库和用户的会话。”

• get_postgresql_config

- “显示所有PostgreSQL配置参数。” - “查找所有与内存相关的配置设置。”

• get_tabase_list

- “列出所有数据库及其大小。” - “显示包含所有者信息的数据库列表。”

• get_table_list

- “列出电子商务数据库中的所有表。” - “显示公共架构中的表大小。”

• get_table_schema_info

- “显示电子商务数据库中客户表的详细架构信息。” - “获取电子商务数据库中产品表的列详细信息和约束。” - “使用索引和外键分析电子商务数据库销售模式中订单表的表结构。” - “显示库存数据库公共架构中所有表的架构概述。” - 📋 特性：列类型、约束、索引、外键、表元数据 - ⚠️ 必需: database_name 必须指定参数

• get_database_schema_info

- “显示电子商务数据库中的所有模式及其内容。” - “在电子商务数据库中获取有关销售模式的详细信息。” - “分析库存数据库的架构结构和权限。” - “显示hr_system数据库的架构概述，包括表计数和大小。” - 📋 特性：架构所有者、权限、对象计数、大小、内容 - ⚠️ 必需: database_name 必须指定参数

• get_table_关系

- “显示电子商务数据库中客户表的所有关系。” - “分析电子商务数据库销售模式中订单表的外键关系。” - “获取电子商务数据库的数据库范围关系概述。” - “查找电子商务数据库中引用产品表的所有表。” - “显示库存数据库中的跨架构关系。” - 📋 特性：外键关系（入站/出站）、跨模式依赖关系、约束详细信息 - ⚠️ 必需: database_name 必须指定参数 - 💡 用法：离开 table_name 数据库范围的关系分析为空

• get_user_list

- “列出所有数据库用户及其角色。” - “显示特定数据库的用户权限。”

• get_index_usage_stats

- “分析索引使用效率。” - “查找当前数据库中未使用的索引。”

• get_database_size_info

- “显示数据库容量分析。” - “按大小查找最大的数据库。”

• get_table_size_info

- “显示表和索引大小分析。” - “在特定架构中查找最大的表。”

• get_vacuum_analyze_status

- “显示最近的VACUUM和ANALYZE操作。” - “列出需要VACUUM的表。”

• get_current数据库信息

- “我连接到哪个数据库？” - “显示当前数据库信息和连接详细信息。” - 显示数据库编码、排序规则和大小信息 - 📋 特性：数据库名称、编码、排序规则、大小、连接限制 - 🔧 PostgreSQL 12-18：完全兼容，无需扩展

• get_table_bloat_分析

- “分析当前数据库中的表膨胀。” - “显示user_logs表模式的死元组比率和膨胀估计。” - “查找需要VACUUM维护的高膨胀表。” - “分析特定模式中至少有100个死元组的膨胀。” - 📋 特性：死元组比率、膨胀大小估计、VACUUM建议、模式过滤 - 🔧 PostgreSQL 12-18：完全兼容，无需扩展 - 💡 用法：使用pg_stat_user_tables的独立扩展方法

• get_database_bloat_overview

- “按架构显示数据库范围的膨胀摘要。” - “获得跨所有模式的存储效率的高级视图。” - “确定需要维护注意的模式。” - 📋 特性：架构级聚合、总膨胀估计、维护状态 - 🔧 PostgreSQL 12-18：完全兼容，无需扩展

• 获取autovacuum_status

- “检查自动真空配置和触发条件。” - “显示需要立即自动吸尘的桌子。” - “分析公共架构的自动清空阈值百分比。” - “查找接近自动真空触发点的桌子。” - 📋 特性：触发阈值分析、紧急程度分类、配置状态 - 🔧 PostgreSQL 12-18：完全兼容，无需扩展 - 💡 用法：使用pg_stat_user_tables进行独立于扩展的自动真空监测

• 获取autovacuum_activity

- “显示过去48小时的自动吸尘器活动模式。” - “监控自动真空执行频率和时间。” - “查找具有不规则自动吸尘模式的桌子。” - “分析最近的自动吸尘器和自动分析历史。” - 📋 特性：活动模式、执行频率、时间分析 - 🔧 PostgreSQL 12-18：完全兼容，无需扩展 - 💡 用法：历史自动真空模式分析

• get_runing_vacuum_操作

- “显示当前正在运行的VACUUM和ANALYZE操作。” - “监控主动维护操作及其进度。” - “检查是否有任何VACUUM操作正在阻止查询。” - “查找长时间运行的维护操作。” - 📋 特性：实时运行状态、运行时间、影响程度、流程详细信息 - 🔧 PostgreSQL 12-18：完全兼容，无需扩展 - 💡 用法：使用pg_stat_activity进行实时维护监控

• 有效性分析

- “分析VACUUM的有效性和维护模式。” - “比较手动真空与自动真空效率。” - “查找具有次优维护模式的表。” - “检查VACUUM频率与表活动比率。” - 📋 特性：维护模式分析、有效性评估、DML与VACUUM比率 - 🔧 PostgreSQL 12-18：完全兼容，无需扩展 - 💡 用法：使用现有统计数据进行战略性真空分析

• get_lock_monitoring

- “显示所有当前锁定和阻止的会话。” - “仅显示具有授予=false筛选器的已阻止会话。” - “使用用户名筛选器按特定用户监视锁。” - “使用模式过滤器检查独占锁。”

• 获取_状态

- “显示WAL状态和存档信息。” - “监控WAL生成和当前LSN位置。”

• 获取应用状态

- “检查复制连接和延迟状态。” - “监视复制插槽和WAL接收器状态。”

• get_database_stats

- “显示全面的数据库性能指标。” - “分析事务提交率和I/O统计数据。” - “监视缓冲区缓存命中率和临时文件使用情况。”

• get_bgwriter_status

- “分析检查点性能和时间。” - “显示检查点性能。” - “显示后台编写器效率统计数据。” - “监视缓冲区分配和fsync模式。”

• get_user_functions_status

- “分析用户定义的函数性能。” - “显示函数调用计数和执行时间。” - “识别自定义函数中的性能瓶颈。” - ⚠️ 需要: track_functions = pl 在postgresql.conf中

• get_table_io_tasts

- “分析表I/O性能和缓冲区命中率。” - “识别缓冲区缓存性能较差的表。” - “监视TOAST表I/O统计信息。” - 💡 增强与: track_io_timing = on 精确计时

• get_index_io_tasts

- “显示索引I/O性能和缓冲区效率。” - “识别导致磁盘I/O过多的索引。” - “监视索引缓存友好性模式。” - 💡 增强与: track_io_timing = on 精确计时

• get_database_conconflicts_stats

- “检查备用服务器上的复制冲突。” - “分析冲突类型和解决统计数据。” - “监视备用服务器查询取消模式。” - “监控WAL生成和当前LSN位置。”

• 获取应用状态

- “检查复制连接和延迟状态。” - “监视复制插槽和WAL接收器状态。”

🚀 版本感知工具（自动适应）

• get_iostats 新

- “显示全面的I/O统计数据。”（PostgreSQL 16+提供了详细的细分） - “分析I/O统计数据。” - “分析缓冲区缓存效率和I/O时序。” - “按后端类型和上下文监视I/O模式。” - 📈 第16页+：完整的pg_stat_io，包括时间、后端类型和上下文 - 📊 第12-15页：基本pg_statio\_\*回退，带缓冲区命中率

• get_bgwriter_status （增强！）

- “显示后台写入程序和检查点性能。” - 📈 第17页+：通过以下方式分离检查指针和bgwriter统计信息 pg_stat_checkpointer - 📊 第12-16页：组合bgwriter统计数据（包括检查指针数据）

• get_server_info （增强！）

- “显示服务器版本和兼容性功能。” - “检查服务器兼容性。” - “检查此PostgreSQL版本上可用的MCP工具。” - “显示功能可用性矩阵和升级建议。”

• get_all_tables_stats （增强！）

- “显示所有表的综合统计数据。”（与PG12-18兼容的版本） - “使用Include_system=true参数包含系统表。” - “分析表访问模式和维护需求。” - 📈 第13页+：跟踪真空后的插入情况(n_ins_since_vacuum)优化维护计划 - 📊 第12页：对于不支持的列，兼容NULL模式

• 获取等待事件 新

- “显示等待事件类型和描述。” - “此PostgreSQL版本上有哪些等待事件？” - 📈 第17页+：本地 pg_wait_events 带有完整描述的目录 - 📊 第12-16页：回退到 pg_stat_activity 按类型分组的当前等待

• get_wal_summarizer_status （新增！PG 17+）

- “显示增量备份的WAL摘要器状态。” - “监控WAL总结进度。” - 📈 第17页+：通过以下方式监控WAL汇总器 pg_get_wal_summarizer_state() - ❌ 第12-16页：不可用（返回信息性消息）

• 获取同步状态 （新增！PG 18+）

- “显示异步I/O子系统状态。” - “监视pg_aios的异步I/O操作。” - 📈 第18页+: pg_aios 异步I/O监控视图 - ❌ 第12-17页：不可用（返回信息性消息）

• get_per-backend_io_tasts （新增！PG 18+）

- “显示每个后端I/O和WAL统计信息。” - “按单个后端进程分析I/O模式。” - 📈 第18页+：每个后端I/O统计数据和WAL统计数据 - ❌ 第12-17页：不可用（返回信息性消息）

🟡 扩展依赖工具

• get_pg_stat_statements_top_查询 （需要 pg_stat_statements)

- “显示前10个最慢的查询。” - “分析库存数据库中的慢速查询。” - 📈 版本兼容：PG12用途 total_time → total_exec_time 测绘；PG13+使用本机列 - 💡 交叉版本：自动调整查询结构以兼容PostgreSQL 12-18

• get_pg_stat_monitor_recent_查询 （可选，使用 pg_stat_monitor)

- “实时显示最近的查询。” - “监视过去5分钟的查询活动。” - 📈 版本兼容：PG12用途 total_time → total_exec_time 测绘；PG13+使用本机列 - 💡 交叉版本：自动调整查询结构以兼容PostgreSQL 12-18

💡 专业建议：所有工具都支持使用 database_name 参数。这允许PostgreSQL超级用户从单个MCP服务器实例分析和监视多个数据库。

______________________________________________________________________

故障排除

连接问题

1. 检查PostgreSQL服务器状态
2. 验证中的连接参数 .env 文件
3. 确保网络连接
4. 检查用户权限

扩展错误

1. 跑 get_server_info 检查分机状态
2. 安装缺少的扩展：

   CREATE EXTENSION pg_stat_statements;
   CREATE EXTENSION pg_stat_monitor;

1. 如果需要，重新启动PostgreSQL

配置问题

1. 函数统计“未找到数据”：检查 track_functions 设置

   SHOW track_functions;  -- Should be 'pl' or 'all'

托管服务（AWS RDS等）的快速修复:

   ALTER SYSTEM SET track_functions = 'pl';
   SELECT pg_reload_conf();

1. 缺少I/O定时数据：启用定时收集

   SHOW track_io_timing;  -- Should be 'on'

快速修复:

   ALTER SYSTEM SET track_io_timing = 'on';
   SELECT pg_reload_conf();

1. 应用配置更改:

- 自我管理：将设置添加到 postgresql.conf 并重新启动服务器 - 托管服务：使用 ALTER SYSTEM SET + SELECT pg_reload_conf() - 临时测试：使用 SET parameter = value 本届会议 - 生成一些数据库活动以填充统计信息

性能问题

1. 使用 limit 减少结果大小的参数
2. 在非高峰时段运行监控
3. 运行分析之前检查数据库负载

版本兼容性问题

有关更多详细信息，请参阅 ##工具兼容性矩阵

1. 先运行兼容性检查:

   # "Use get_server_info to check version and available features"

1. 了解功能可用性:

- PostgreSQL 18：所有功能，包括异步I/O、VACUUM定时、每个后端统计数据 - PostgreSQL 17：单独的检查指针统计数据、等待事件、WAL汇总器 - PostgreSQL 16：pg_stat_io视图 - PostgreSQL 14+：并行查询跟踪 - PostgreSQL 12-13：仅核心功能

1. 如果工具显示“不可用”:

- 功能需要较新的PostgreSQL版本 - 工具将自动使用最佳可用替代方案 - 考虑升级PostgreSQL以增强监控

______________________________________________________________________

发展

测试与开发

# Clone and setup for development
git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops
uv sync

# Test with MCP Inspector (loads .env automatically)
./run-mcp-inspector-local.sh

# Direct execution methods:
# 1. Using uv run (recommended for development)
uv run mcp-postgresql-ops --log-level DEBUG

# 2. Module execution (requires PYTHONPATH)
PYTHONPATH=src python -m mcp_postgresql_ops --log-level DEBUG

# 3. After installation
mcp-postgresql-ops --log-level DEBUG

# Test version compatibility (requires different PostgreSQL versions)
# Modify POSTGRES_HOST in .env to point to different versions

运行测试

有两个测试套件可供选择：

uv run pytest 自动启动Docker测试容器（PG 12-18），等待它们完全初始化，运行所有测试，然后删除所有内容。

# Run all tests (unit + integration) — Docker is managed automatically
uv run pytest -v

# Unit tests only (no Docker needed)
uv run pytest tests/test_version_compat.py -v

# Integration tests only
uv run pytest tests/test_tools_integration.py -v

备注：Docker必须正在运行。测试堆栈使用端口5412–5418（PG 12–18）。

版本兼容性测试

MCP服务器自动适应PostgreSQL版本12-18。要跨版本测试，请执行以下操作：

1. 设置测试数据库：不同的PostgreSQL版本（12、14、15、16、17、18）
2. 运行兼容性测试：指向每个版本并验证工具行为
3. 检查特征检测：确保正确的版本检测和功能可用性
4. 验证回退行为：确认旧版本的优雅降级

______________________________________________________________________

安全须知

• 所有工具都是 只读 -无数据修改功能
• 输出中隐藏了敏感信息（密码）
• 不直接执行SQL，只执行预定义查询
• 遵循最小特权原则

______________________________________________________________________

贡献

🤝 有想法吗？发现虫子了吗？想添加酷炫的功能吗？

我们总是很高兴欢迎新的贡献者！无论您是修复拼写错误、添加新的监控工具还是改进文档，每一份贡献都会使这个项目变得更好。

贡献方式：

• 🐛 报告问题或错误
• 💡 建议新的PostgreSQL监控功能
• 📝 改进文档
• 🚀 提交拉取请求
• ⭐ 如果你觉得回购有用，请为其加星！

专业提示： 代码库的设计非常适合添加新工具。查看现有 @mcp.tool() 功能在 mcp_main.py.

______________________________________________________________________

MCPO Swagger文件

\[MCPO Swagger URL\]http://localhost:8003/postgresql-操作/文档

MCPO Swagger APIs

______________________________________________________________________

🔐 安全和身份验证

承载令牌身份验证

对于 streamable-http 模式下，此MCP服务器支持承载令牌身份验证，以确保远程访问的安全。在生产环境中运行服务器时，这一点尤为重要。

默认策略: REMOTE_AUTH_ENABLE 默认为 false 如果未定义、为null或为空。这确保了向后兼容性，并在未设置变量时防止启动错误。

配置

启用身份验证：

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=my-test-secret-key-12345

或者通过CLI：

# Module method
python -m mcp_postgresql_ops --type streamable-http --auth-enable --secret-key my-test-secret-key-12345

# Script method
mcp-postgresql-ops --type streamable-http --auth-enable --secret-key my-test-secret-key-12345

安全等级

1. stdio模式 （默认）：仅本地访问，无需身份验证
2. 可流式传输http+REMOTE_AUTH_ENABLE=false：无身份验证的远程访问⚠️ 不建议用于生产
3. 可流式传输http+REMOTE_AUTH_ENABLE=true：使用承载令牌身份验证进行远程访问✅ 建议用于生产

客户端配置

启用身份验证后，MCP客户端必须在授权标头中包含Bearer令牌：

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer my-test-secret-key-12345"
      }
    }
  }
}

安全最佳实践

• 始终启用身份验证 在生产环境中使用流式http模式时
• 使用强随机生成的密钥 （建议使用32+个字符）
• 使用HTTPS 如果可能（使用SSL/TLS配置反向代理）
• 限制网络访问 使用防火墙或网络策略
• 定期旋转密钥 增强安全性
• 监控访问日志 未经授权的访问尝试

错误处理

当身份验证失败时，服务器返回：

• 401未经授权 用于丢失或无效的令牌
• 详细的错误消息 JSON格式用于调试

______________________________________________________________________

🚀 添加自定义工具

此MCP服务器旨在易于扩展。按照以下4个简单步骤添加您自己的自定义工具：

分步指南

1. 添加辅助函数（可选）

添加可重用的数据函数 src/mcp_postgresql_ops/functions.py:

async def get_your_custom_data(target_database: str = None, limit: int = 20) -> List[Dict[str, Any]]:
    """Your custom data retrieval function."""
    try:
        # Example implementation - adapt to your PostgreSQL needs
        query = """
        SELECT 
            schemaname,
            tablename,
            attname as column_name,
            n_distinct,
            most_common_vals,
            most_common_freqs
        FROM pg_stats 
        WHERE schemaname NOT IN ('information_schema', 'pg_catalog')
        ORDER BY schemaname, tablename, attname
        LIMIT $1
        """
        
        results = await execute_query(query, [limit], database=target_database)
        return results
        
    except Exception as e:
        logger.error(f"Failed to get custom data: {e}")
        raise

2. 创建您的MCP工具

将您的工具功能添加到 src/mcp_postgresql_ops/mcp_main.py:

@mcp.tool()
async def get_your_custom_analysis(limit: int = 50, database_name: Optional[str] = None) -> str:
    """
    [Tool Purpose]: Brief description of what your tool does
    
    [Exact Functionality]:
    - Feature 1: Data aggregation and analysis
    - Feature 2: Database monitoring and insights
    - Feature 3: Performance metrics and reporting
    
    [Required Use Cases]:
    - When user asks "your specific analysis request"
    - Your PostgreSQL-specific monitoring needs
    
    Args:
        limit: Maximum results (1-100)
        database_name: Target database name (optional, uses default if not specified)
    
    Returns:
        Formatted analysis results
    """
    try:
        # Always validate input limits
        limit = max(1, min(limit, 100))
        
        # Get your custom data
        results = await get_your_custom_data(target_database=database_name, limit=limit)
        
        if not results:
            return "No data found for custom analysis."
        
        # Format and return results
        return format_table_data(results, f"Custom Analysis Results (Top {len(results)})")
        
    except Exception as e:
        logger.error(f"Failed to get custom analysis: {e}")
        return f"Error: {str(e)}"

3. 更新导入

将辅助函数添加到中的导入部分 src/mcp_postgresql_ops/mcp_main.py （第30行附近）：

from .functions import (
    execute_query,
    execute_single_query,
    format_table_data,
    format_bytes,
    format_duration,
    get_server_version,
    check_extension_exists,
    get_pg_stat_statements_data,
    get_pg_stat_monitor_data,
    sanitize_connection_info,
    read_prompt_template,
    parse_prompt_sections,
    get_current_database_name,
    POSTGRES_CONFIG,
    get_your_custom_data,  # Add your new function here
)

4. 更新提示模板（推荐）

将您的工具描述添加到 src/mcp_postgresql_ops/prompt_template.md 为了更好地识别自然语言：

### **Your Custom Analysis Tool**

### X. **get_your_custom_analysis**
**Purpose**: Brief description of what your tool does
**Usage**: "Show me your custom analysis" or "Get custom analysis for database_name"
**Features**: Data aggregation, database monitoring, performance metrics
**Optional**: `database_name` parameter for specific database analysis
**Limit**: Results limited to 1-100 records for performance

5. 测试你的工具

# Local testing with MCP Inspector
./run-mcp-inspector-local.sh

# Or test with Docker stack
docker-compose up -d
docker-compose logs -f mcp-server

# Test with natural language queries:
# "Show me your custom analysis"
# "Get custom analysis for ecommerce database"
# "Analyze custom data with limit 25"

重要说明

• 多数据库支持：所有工具都支持可选 database_name 针对特定数据库的参数
• 输入验证：始终验证 limit 参数与 max(1, min(limit, 100))
• 错误处理：返回用户友好的错误消息，而不是引发异常
• 日志记录：使用 logger.error() 用于调试，同时向用户返回干净的错误消息
• PostgreSQL兼容性：您的自定义查询应该在PostgreSQL 12-18中工作
• 扩展依赖关系：如果您的工具需要特定的扩展，请通过以下方式检查可用性 check_extension_exists()

高级模式

对于版本感知查询或依赖扩展的功能，请参阅现有的工具，如 get_pg_stat_statements_top_queries 作为参考图案。

就是这样！您的自定义工具已准备好通过任何MCP客户端与自然语言查询一起使用。

______________________________________________________________________

许可证

自由使用、修改和分发 MIT许可证.

______________________________________________________________________

⭐ 其他项目

同一作者的其他MCP服务器：

• MCP-气流API
• MCP-Ambari-API公司
• MCP-OpenStack-API
• LogSentinelAI-基于LLB的日志分析器