MCP Postgresql Ops

🚀 PostgreSQL操作與監控MCP服務器

MCP-PostgreSQL-Ops 是一款專業的MCP服務器，用於對PostgreSQL數據庫進行操作、監控和管理。它支持PostgreSQL 12 - 17版本，可通過自然語言查詢實現全面的數據庫分析、性能監控以及智能維護建議。大部分功能可獨立運行，但在安裝 pg_stat_statements 和（可選）pg_stat_monitor 擴展後，高級查詢分析功能將得到增強。

✨ 主要特性

• ✅ 零配置：可直接與PostgreSQL 12 - 17版本配合使用，自動檢測版本。
• ✅ 自然語言交互：支持使用自然語言提問，例如 “顯示慢查詢” 或 “分析表膨脹情況”。
• ✅ 生產環境安全：僅執行只讀操作，兼容RDS/Aurora，普通用戶權限即可使用。
• ✅ 擴展增強：可選安裝 pg_stat_statements 和 pg_stat_monitor 擴展，以實現高級查詢分析。
• ✅ 全面的數據庫監控：提供性能分析、表膨脹檢測和維護建議。
• ✅ 智能查詢分析：通過集成 pg_stat_statements 和 pg_stat_monitor 識別慢查詢。
• ✅ 模式與關係發現：探索數據庫結構，提供詳細的關係映射。
• ✅ VACUUM與自動清理智能分析：即時監控維護操作並分析其有效性。
• ✅ 多數據庫操作：無縫進行跨數據庫分析和監控。
• ✅ 企業級適用：安全的只讀操作，兼容RDS/Aurora。
• ✅ 開發者友好：代碼結構簡單，易於定製和擴展工具功能。

🔧 高級功能

• 支持版本感知的I/O統計（在PostgreSQL 16+版本中增強）。
• 即時監控連接和鎖狀態。
• 分析後臺進程和檢查點。
• 監控複製狀態和WAL日誌。
• 分析數據庫容量和表膨脹情況。

🚀 快速開始

⚠️ 重要提示

docker-compose.yml 中包含的 postgresql 容器僅用於快速啟動測試。您可以根據需要調整環境變量，連接到自己的PostgreSQL實例。

💡 使用建議

若要使用自己的PostgreSQL實例而非內置測試容器，請按以下步驟操作：

• 更新 .env 文件中的目標PostgreSQL連接信息（請參考 POSTGRES_HOST、POSTGRES_PORT、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB）。
• 在 docker-compose.yml 中註釋掉（禁用）postgres 和 postgres-init-extensions 容器，以避免啟動內置測試數據庫。

1. 環境設置

⚠️ 重要提示

雖然超級用戶權限可以訪問所有數據庫和系統信息，但MCP服務器使用普通用戶權限也能執行基本的監控任務。

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

### 檢查並修改.env文件
cp .env.example .env
vim .env

### 無需修改默認值，但如果使用自己的PostgreSQL服務器，請編輯以下內容：
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432  # 主機訪問的外部端口（映射到內部5432）
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # 默認連接的數據庫。超級用戶可以訪問所有數據庫。

⚠️ 重要提示

PGDATA=/data/db 是為Percona PostgreSQL Docker鏡像預先配置的，該鏡像需要此特定路徑以確保正確的寫入權限。

2. 啟動演示容器

# 啟動所有容器，包括內置的PostgreSQL進行測試
docker-compose up -d

# 替代方案：如果使用自己的PostgreSQL實例
# 在docker-compose.yml中註釋掉postgres和postgres-init-extensions服務
# 然後使用自定義配置：
# docker-compose -f docker-compose.custom-db.yml up -d

⚠️ 重要提示

初始環境設置需要幾分鐘時間，因為容器按以下順序啟動：

1. PostgreSQL 容器首先啟動並初始化數據庫。
2. PostgreSQL擴展 容器安裝擴展並創建全面的測試數據（約83K條記錄）。
3. MCP服務器 和 MCPO代理 容器在PostgreSQL準備好後啟動。
4. OpenWebUI 容器最後啟動，加載Web界面可能需要額外的時間。

💡 使用建議

運行 docker-compose up -d 後等待2 - 3分鐘再訪問OpenWebUI，以確保所有服務完全初始化。

🔍 檢查容器狀態（可選）：

# 監控容器啟動進度
docker-compose logs -f

# 檢查所有容器是否正在運行
docker-compose ps

# 驗證PostgreSQL是否準備好
docker-compose logs postgres | grep "ready to accept connections"

3. 訪問OpenWebUI

訪問地址：http://localhost:3003/

• 由 swagger 提供的MCP工具功能列表可在MCPO API文檔URL中找到。
  • 例如：http://localhost:8003/docs

4. 在OpenWebUI中註冊工具

1. 使用管理員賬戶登錄OpenWebUI。
2. 從頂部菜單中選擇 “設置” → “工具”。
3. 輸入 postgresql-ops 工具地址（例如，http://localhost:8003/postgresql-ops）以連接MCP工具。
4. 設置Ollama或OpenAI。

5. 完成！

恭喜！ 您的MCP PostgreSQL操作服務器現已可以使用。您可以開始使用自然語言查詢探索您的數據庫。

🚀 嘗試以下示例查詢：

• “顯示當前活動連接”
• “系統中最慢的查詢有哪些？”
• “分析所有數據庫中的表膨脹情況”
• “顯示數據庫大小信息”
• “哪些表需要進行VACUUM維護？”

💻 使用示例

Claude桌面集成

（推薦）將以下內容添加到您的Claude桌面配置文件中：

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

（可選）使用本地源代碼運行：

{
  "mcpServers": {
    "postgresql-ops": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.mcp_postgresql_ops.mcp_main"],
      "env": {
        "PYTHONPATH": "/path/to/MCP-PostgreSQL-Ops",
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

獨立運行MCP服務器

使用Pypi和uvx（推薦）

# 標準輸入輸出模式
uvx --python 3.11 mcp-postgresql-ops \
  --type stdio

# HTTP模式
uvx --python 3.11 mcp-postgresql-ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --log-level DEBUG

（可選）配置多個PostgreSQL實例

{
  "mcpServers": {
    "Postgresql-A": {
      "command": "uvx",
      "args": ["--python", "3.11", "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.11", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "b.bar.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    }
  }
}

使用本地源代碼

# 標準輸入輸出模式
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops
python -m src.mcp_postgresql_ops.mcp_main \
  --type stdio

# HTTP模式
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops
python -m src.mcp_postgresql_ops.mcp_main \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --log-level DEBUG

📚 詳細文檔

環境變量

⚠️ 重要提示

POSTGRES_DB 是在未指定特定數據庫時操作的默認目標數據庫。在Docker環境中，如果設置為非默認名稱，該數據庫將在PostgreSQL首次啟動時自動創建。

💡 使用建議

內置的PostgreSQL容器使用端口映射 15432:5432，其中：

• POSTGRES_PORT = 15432：主機訪問和MCP服務器連接的外部端口。
• DOCKER_INTERNAL_PORT_POSTGRESQL = 5432：容器內部端口（PostgreSQL默認）。
• 使用外部PostgreSQL服務器時，請將 POSTGRES_PORT 設置為與服務器實際端口匹配。

先決條件

所需的PostgreSQL擴展

⚠️ 重要提示

有關更多詳細信息，請參閱 工具兼容性矩陣。

💡 使用建議

大多數MCP工具無需任何PostgreSQL擴展即可工作。一些高級性能分析工具需要以下擴展：

-- 查詢性能統計（僅 `get_pg_stat_statements_top_queries` 需要）
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 高級監控（可選，`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上測試）
• Python 3.11
• 能夠訪問PostgreSQL服務器的網絡連接
• 對系統目錄的讀取權限

所需的PostgreSQL配置

⚠️ 重要提示

一些MCP工具需要特定的PostgreSQL配置參數來收集統計信息。請選擇以下配置方法之一：

💡 使用建議

受這些設置影響的工具：

• get_user_functions_stats：需要 track_functions = pl 或 track_functions = all。
• get_table_io_stats 和 get_index_io_stats：track_io_timing = on 可提供更準確的計時。
• get_database_stats：track_io_timing = on 可增強I/O計時。

⚠️ 重要提示

應用任何方法後，驗證設置：

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 中添加以下內容：

# 基本統計信息收集（通常默認啟用）
track_activities = on
track_counts = on

# 函數統計工具所需
track_functions = pl    # 啟用PL/pgSQL函數統計信息收集

# 可選但推薦用於準確的I/O計時
track_io_timing = on    # 啟用I/O計時統計信息收集

然後重啟PostgreSQL服務器。

方法2：PostgreSQL啟動參數

對於Docker或命令行啟動的PostgreSQL：

# Docker示例
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

# 直接使用postgres命令
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.conf 的託管PostgreSQL服務，使用SQL命令動態更改設置：

-- 啟用基本統計信息收集（通常默認啟用）
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';

-- 啟用函數統計信息收集（需要超級用戶權限）
ALTER SYSTEM SET track_functions = 'pl';

-- 啟用I/O計時統計信息（可選但推薦）
ALTER SYSTEM SET track_io_timing = 'on';

-- 不重啟重新加載配置（單獨運行）
SELECT pg_reload_conf();

💡 使用建議

會話級測試的替代方法：

-- 僅為當前會話設置（臨時）
SET track_activities = 'on';
SET track_counts = 'on';
SET track_functions = 'pl';
SET track_io_timing = 'on';

⚠️ 重要提示

使用命令行工具時，分別運行每個SQL語句，以避免事務塊錯誤。

RDS/Aurora兼容性

• 此服務器為只讀模式，可與RDS/Aurora上的普通角色配合使用。若要進行高級分析，請啟用 pg_stat_statements；pg_stat_monitor 在託管引擎上不可用。
• 在RDS/Aurora上，建議使用數據庫參數組而非 ALTER SYSTEM 進行持久設置。

-- 驗證預加載設置
SHOW shared_preload_libraries;

-- 在目標數據庫中啟用擴展
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 推薦的監控可見性
GRANT pg_read_all_stats TO <app_user>;

示例查詢

🟢 無需擴展的工具（始終可用）

• get_server_info
  • “顯示PostgreSQL服務器版本和擴展狀態。”
  • “檢查是否安裝了 pg_stat_statements。”
• get_active_connections
  • “顯示所有活動連接。”
  • “列出當前會話的數據庫和用戶信息。”
• get_postgresql_config
  • “顯示所有PostgreSQL配置參數。”
  • “查找所有與內存相關的配置設置。”
• get_database_list
  • “列出所有數據庫及其大小。”
  • “顯示帶有所有者信息的數據庫列表。”
• get_table_list
  • “列出 ecommerce 數據庫中的所有表。”
  • “顯示 public 模式下表的大小。”
• get_table_schema_info
  • “顯示 ecommerce 數據庫中 customers 表的詳細模式信息。”
  • “獲取 ecommerce 數據庫中 products 表的列詳細信息和約束。”
  • “分析 ecommerce 數據庫 sales 模式中 orders 表的表結構，包括索引和外鍵。”
  • “顯示 inventory 數據庫 public 模式中所有表的模式概述。”
  • 📋 功能：列類型、約束、索引、外鍵、表元數據
  • ⚠️ 必需：必須指定 database_name 參數
• get_database_schema_info
  • “顯示 ecommerce 數據庫中所有模式及其內容。”
  • “獲取 ecommerce 數據庫中 sales 模式的詳細信息。”
  • “分析 inventory 數據庫的模式結構和權限。”
  • “顯示 hr_system 數據庫的模式概述，包括表計數和大小。”
  • 📋 功能：模式所有者、權限、對象計數、大小、內容
  • ⚠️ 必需：必須指定 database_name 參數
• get_table_relationships
  • “顯示 ecommerce 數據庫中 customers 表的所有關係。”
  • “分析 ecommerce 數據庫 sales 模式中 orders 表的外鍵關係。”
  • “獲取 ecommerce 數據庫的全數據庫關係概述。”
  • “查找 ecommerce 數據庫中引用 products 表的所有表。”
  • “顯示 inventory 數據庫中的跨模式關係。”
  • 📋 功能：外鍵關係（入站/出站）、跨模式依賴關係、約束詳細信息
  • ⚠️ 必需：必須指定 database_name 參數
  • 💡 使用方法：留空 table_name 可進行全數據庫關係分析
• get_user_list
  • “列出所有數據庫用戶及其角色。”
  • “顯示特定數據庫的用戶權限。”
• get_index_usage_stats
  • “分析索引使用效率。”
  • “查找當前數據庫中未使用的索引。”
• get_database_size_info
  • “顯示數據庫容量分析。”
  • “查找按大小排序的最大數據庫。”
• get_table_size_info
  • “顯示錶和索引大小分析。”
  • “查找特定模式中最大的表。”
• get_vacuum_analyze_stats
  • “顯示最近的VACUUM和ANALYZE操作。”
  • “列出需要VACUUM的表。”
• get_current_database_info
  • “我當前連接到哪個數據庫？”
  • “顯示當前數據庫信息和連接詳細信息。”
  • “顯示數據庫編碼、排序規則和大小信息。”
  • 📋 功能：數據庫名稱、編碼、排序規則、大小、連接限制
  • 🔧 PostgreSQL 12 - 17：完全兼容，無需擴展
• get_table_bloat_analysis
  • “分析當前數據庫中的表膨脹情況。”
  • “顯示 ecommerce 數據庫中死元組比率較高的表。”
  • “查找需要VACUUM維護的表。”
  • “檢查死元組超過5000個的表的膨脹情況。”
  • 📋 功能：死元組比率、估計的膨脹大小、VACUUM建議
  • ⚠️ 必需：跨數據庫分析時必須指定 database_name
• get_database_bloat_overview
  • “按模式顯示全數據庫的膨脹摘要。”
  • “獲取 inventory 數據庫的膨脹概述。”
  • “識別膨脹比率最高的模式。”
  • “根據膨脹統計信息進行數據庫維護規劃。”
  • 📋 功能：模式級聚合、維護優先級、大小建議
• get_autovacuum_status
  • “檢查自動清理配置和觸發條件。”
  • “顯示需要立即進行自動清理的表。”
  • “分析 public 模式的自動清理閾值百分比。”
  • “查找接近自動清理觸發點的表。”
  • 📋 功能：觸發閾值分析、緊急程度分類、配置狀態
  • 🔧 PostgreSQL 12 - 17：完全兼容，無需擴展
  • 💡 使用方法：使用 pg_stat_user_tables 進行無需擴展的自動清理監控
• get_autovacuum_activity
  • “顯示過去48小時的自動清理活動模式。”
  • “監控自動清理執行頻率和時間。”
  • “查找自動清理模式不規則的表。”
  • “分析最近的自動清理和自動分析歷史。”
  • 📋 功能：活動模式、執行頻率、時間分析
  • 🔧 PostgreSQL 12 - 17：完全兼容，無需擴展
  • 💡 使用方法：歷史自動清理模式分析
• get_running_vacuum_operations
  • “顯示當前正在運行的VACUUM和ANALYZE操作。”
  • “監控活動的維護操作及其進度。”
  • “檢查是否有VACUUM操作阻塞查詢。”
  • “查找長時間運行的維護操作。”
  • 📋 功能：即時操作狀態、已用時間、影響級別、進程詳細信息
  • 🔧 PostgreSQL 12 - 17：完全兼容，無需擴展
  • 💡 使用方法：使用 pg_stat_activity 進行即時維護監控
• get_vacuum_effectiveness_analysis
  • “分析VACUUM有效性和維護模式。”
  • “比較手動VACUUM和自動清理的效率。”
  • “查找維護模式不佳的表。”
  • “檢查VACUUM頻率與表活動比率。”
  • 📋 功能：維護模式分析、有效性評估、DML與VACUUM比率
  • 🔧 PostgreSQL 12 - 17：完全兼容，無需擴展
  • 💡 使用方法：使用現有統計信息進行戰略性VACUUM分析
• get_table_bloat_analysis
  • “分析 public 模式中的表膨脹情況。”
  • “顯示 ecommerce 數據庫中死元組比率較高的表。”
  • “查找需要VACUUM維護的表。”
  • “檢查死元組超過5000個的表的膨脹情況。”
  • 📋 功能：死元組比率、估計的膨脹大小、VACUUM建議
  • ⚠️ 必需：跨數據庫分析時必須指定 database_name
• get_database_bloat_overview
  • “按模式顯示全數據庫的膨脹摘要。”
  • “獲取 inventory 數據庫的膨脹概述。”
  • “識別膨脹比率最高的模式。”
  • “根據膨脹統計信息進行數據庫維護規劃。”
  • 📋 功能：模式級聚合、維護優先級、大小建議
• get_lock_monitoring
  • “顯示所有當前鎖和阻塞的會話。”
  • “僅顯示 granted = false 過濾後的阻塞會話。”
  • “使用用戶名過濾器按特定用戶監控鎖。”
  • “使用模式過濾器檢查排他鎖。”
• get_wal_status
  • “顯示WAL狀態和歸檔信息。”
  • “監控WAL生成和當前LSN位置。”
• get_replication_status
  • “檢查複製連接和延遲狀態。”
  • “監控複製槽和WAL接收器狀態。”
• get_database_stats
  • “顯示全面的數據庫性能指標。”
  • “分析事務提交比率和I/O統計信息。”
  • “監控緩衝區緩存命中率和臨時文件使用情況。”
• get_bgwriter_stats
  • “分析檢查點性能和時間。”
  • “顯示檢查點性能。”
  • “顯示後臺寫入器效率統計信息。”
  • “監控緩衝區分配和fsync模式。”
• get_user_functions_stats
  • “分析用戶定義函數的性能。”
  • “顯示函數調用計數和執行時間。”
  • “識別自定義函數中的性能瓶頸。”
  • ⚠️ 需要：postgresql.conf 中 track_functions = pl
• get_table_io_stats
  • “分析表I/O性能和緩衝區命中率。”
  • “識別緩衝區緩存性能不佳的表。”
  • “監控TOAST表的I/O統計信息。”
  • 💡 增強功能：track_io_timing = on 可提供更準確的計時
• get_index_io_stats
  • “顯示索引I/O性能和緩衝區效率。”
  • “識別導致過多磁盤I/O的索引。”
  • “監控索引緩存友好性模式。”
  • 💡 增強功能：track_io_timing = on 可提供更準確的計時
• get_database_conflicts_stats
  • “檢查備用服務器上的複製衝突。”
  • “分析衝突類型和解決統計信息。”
  • “監控備用服務器查詢取消模式。”
  • “監控WAL生成和當前LSN位置。”
• get_replication_status
  • “檢查複製連接和延遲狀態。”
  • “監控複製槽和WAL接收器狀態。”

🚀 版本感知工具（自動適應）

• get_io_stats（新增！）
  • “顯示全面的I/O統計信息。”（PostgreSQL 16+提供詳細細分）
  • “分析I/O統計信息。”
  • “分析緩衝區緩存效率和I/O時間。”
  • “按後端類型和上下文監控I/O模式。”
  • 📈 PG16+：完整的 pg_stat_io 支持，包括計時、後端類型和上下文
  • 📊 PG12 - 15：基本的 pg_statio_* 回退，提供緩衝區命中率
• get_bgwriter_stats（增強！）
  • “顯示後臺寫入器和檢查點性能。”
  • 📈 PG15：單獨的檢查點器和後臺寫入器統計信息（獨特功能）
  • 📊 PG12 - 14, 16+：合併的後臺寫入器統計信息（包括檢查點器數據）
• get_server_info（增強！）
  • “顯示服務器版本和兼容性功能。”
  • “檢查服務器兼容性。”
  • “檢查此PostgreSQL版本上可用的MCP工具。”
  • “顯示功能可用性矩陣和升級建議。”
• get_all_tables_stats（增強！）
  • “顯示所有表的全面統計信息。”（PG12 - 17版本兼容）
  • “使用 include_system = true 參數包括系統表。”
  • “分析表訪問模式和維護需求。”
  • 📈 PG13+：跟蹤自上次VACUUM以來的插入次數（n_ins_since_vacuum），以優化維護計劃
  • 📊 PG12：兼容模式，不支持的列顯示為NULL

🟡 需要擴展的工具

• get_pg_stat_statements_top_queries（需要 pg_stat_statements）
  • “顯示前10個最慢的查詢。”
  • “分析 inventory 數據庫中的慢查詢。”
  • 📈 版本兼容：PG12使用 total_time → total_exec_time 映射；PG13+使用原生列
  • 💡 跨版本：自動調整查詢結構以兼容PostgreSQL 12 - 17
• get_pg_stat_monitor_recent_queries（可選，使用 pg_stat_monitor）
  • “即時顯示最近的查詢。”
  • “監控過去5分鐘的查詢活動。”
  • 📈 版本兼容：PG12使用 total_time → total_exec_time 映射；PG13+使用原生列
  • 💡 跨版本：自動調整查詢結構以兼容PostgreSQL 12 - 17

💡 使用建議

所有工具都支持使用 database_name 參數進行多數據庫操作。這允許PostgreSQL超級用戶從單個MCP服務器實例分析和監控多個數據庫。

工具兼容性矩陣

🟢 無需擴展的工具（始終可用）

🚀 版本感知工具（自動適應）

🟡 需要擴展的工具

⚠️ 重要提示

PostgreSQL 18支持：PostgreSQL 18目前處於測試階段，Percona Distribution PostgreSQL尚未支持。待PostgreSQL 18達到穩定版本並提供發行版支持後，將添加相應支持。

故障排除

連接問題

1. 檢查PostgreSQL服務器狀態。
2. 驗證 .env 文件中的連接參數。
3. 確保網絡連接正常。
4. 檢查用戶權限。

擴展錯誤

1. 運行 get_server_info 檢查擴展狀態。
2. 安裝缺失的擴展：

CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pg_stat_monitor;

3. 如有需要，重啟PostgreSQL。

配置問題

1. 函數統計信息顯示 “未找到數據”：檢查 track_functions 設置

SHOW track_functions;  -- 應為 'pl' 或 'all'

💡 使用建議

託管服務（如AWS RDS等）的快速修復方法：

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

2. 缺少I/O計時數據：啟用計時收集

SHOW track_io_timing;  -- 應為 'on'

💡 使用建議

快速修復方法：

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

3. 應用配置更改：

• 自管理：將設置添加到 postgresql.conf 並重啟服務器。
• 託管服務：使用 ALTER SYSTEM SET + SELECT pg_reload_conf()。
• 臨時測試：使用 SET parameter = value 為當前會話設置。
• 生成一些數據庫活動以填充統計信息。

性能問題

1. 使用 limit 參數減少結果集大小。
2. 在非高峰時段運行監控。
3. 在運行分析之前檢查數據庫負載。

版本兼容性問題

⚠️ 重要提示

有關更多詳細信息，請參閱 工具兼容性矩陣。

1. 首先運行兼容性檢查：

# "使用 get_server_info 檢查版本和可用功能"

2. 瞭解功能可用性：

• PostgreSQL 16 - 17：所有功能可用。
• PostgreSQL 15+：單獨的檢查點器統計信息。
• PostgreSQL 14+：並行查詢跟蹤。
• PostgreSQL 12 - 13：僅核心功能。

3. 如果工具顯示 “不可用”：

• 該功能需要較新的PostgreSQL版本。
• 工具將自動使用最佳可用替代方案。
• 考慮升級PostgreSQL以獲得增強的監控功能。

🔧 技術細節

測試與開發

# 使用MCP檢查器進行測試
./scripts/run-mcp-inspector-local.sh

# 直接執行以進行調試
python -m src.mcp_postgresql_ops.mcp_main --log-level DEBUG

# 測試版本兼容性（需要不同的PostgreSQL版本）
# 修改.env中的POSTGRES_HOST以指向不同版本

# 運行測試（如果有）
uv run pytest

版本兼容性測試

MCP服務器可自動適應PostgreSQL 12 - 17版本。要跨版本進行測試：

1. 設置測試數據庫：使用不同的PostgreSQL版本（12、14、15、16、17）。
2. 運行兼容性測試：指向每個版本並驗證工具行為。
3. 檢查功能檢測：確保正確檢測版本和功能可用性。
4. 驗證回退行為：確認在較舊版本上的優雅降級。

安全說明

• 所有工具均為 只讀 - 無數據修改功能。
• 輸出中會屏蔽敏感信息（如密碼）。
• 不直接執行SQL - 僅使用預定義查詢。
• 遵循最小權限原則。

📄 許可證

本項目遵循 MIT許可證，您可以自由使用、修改和分發。

⭐ 其他項目

由同一作者開發的其他MCP服務器：

• MCP-Airflow-API
• MCP-Ambari-API
• LogSentinelAI - 基於LLB的日誌分析器

🤝 貢獻

我們始終歡迎新的貢獻者！無論您是修復拼寫錯誤、添加新的監控工具還是改進文檔，每一份貢獻都將使這個項目變得更好。

貢獻方式：

• 🐛 報告問題或漏洞。
• 💡 提出新的PostgreSQL監控功能建議。
• 📝 改進文檔。
• 🚀 提交拉取請求。
• ⭐ 如果您覺得這個項目有用，請給它加星！

💡 使用建議

代碼庫的設計非常便於添加新工具。請查看 mcp_main.py 中現有的 @mcp.tool() 函數。

MCPO Swagger文檔

[MCPO Swagger URL] http://localhost:8003/postgresql-ops/docs