Hologres

English | 中文

Hologres MCP Server

Hologres MCP Server 作為 AI 代理與 Hologres 資料庫之間的通用介面，能讓 AI 代理與 Hologres 無縫溝通，協助 AI 代理擷取 Hologres 資料庫的中繼資料並執行 SQL 操作。

設定方式

模式一：使用本機檔案

下載

從 Github 下載

git clone https://github.com/aliyun/alibabacloud-hologres-mcp-server.git

MCP 整合

將下列設定加入 MCP 用戶端設定檔：

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/alibabacloud-hologres-mcp-server",
                "run",
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

模式二：使用 PIP 模式

安裝

使用下列套件安裝 MCP Server：

pip install hologres-mcp-server

MCP 整合

將下列設定加入 MCP 用戶端設定檔：

使用 uv 模式

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "hologres-mcp-server",
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

使用 uvx 模式

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uvx",
            "args": [
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

模式三：使用 Streamable HTTP 傳輸

伺服器支援 Streamable HTTP 傳輸，適用於無法使用 STDIO 的遠端部署場景。

啟動伺服器

啟動伺服器前，請先設定 Hologres 連線環境變數：

export HOLOGRES_HOST="your-hologres-instance.hologres.aliyuncs.com"
export HOLOGRES_PORT="80"
export HOLOGRES_USER="your_access_id"
export HOLOGRES_PASSWORD="your_access_key"
export HOLOGRES_DATABASE="your_database"

然後啟動伺服器：

# Using pip-installed package
hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

# Or using uvx
uvx hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

MCP 端點將可於 http://<host>:<port>/mcp 存取。

CLI 選項

選項	預設值	說明
--transport	stdio	傳輸類型：stdio、streamable-http 或 sse
--host	127.0.0.1	綁定的主機（僅限 HTTP 傳輸）
--port	8000	監聽的埠號（僅限 HTTP 傳輸）

MCP 整合

將下列設定加入 MCP 用戶端設定檔：

{
    "mcpServers": {
        "hologres-mcp-server": {
            "url": "http://<host>:<port>/mcp"
        }
    }
}

與 Claude Code 搭配使用

# Add to Claude Code
claude mcp add hologres-mcp-server \
  -e HOLOGRES_HOST=<your_host> \
  -e HOLOGRES_PORT=<your_port> \
  -e HOLOGRES_USER=<your_access_id> \
  -e HOLOGRES_PASSWORD=<your_access_key> \
  -e HOLOGRES_DATABASE=<your_database> \
  -- uvx hologres-mcp-server

元件

工具

• execute_hg_select_sql：在 Hologres 資料庫中執行 SELECT SQL 查詢
• execute_hg_select_sql_with_serverless：在 Hologres 資料庫中使用無伺服器運算執行 SELECT SQL 查詢
• execute_hg_dml_sql：在 Hologres 資料庫中執行 DML（INSERT、UPDATE、DELETE）SQL 查詢
• execute_hg_ddl_sql：在 Hologres 資料庫中執行 DDL（CREATE、ALTER、DROP、COMMENT ON）SQL 查詢
• gather_hg_table_statistics：收集 Hologres 資料庫中的資料表統計資訊
  • 參數：schema_name（字串）、table（字串）
• get_hg_query_plan：取得 Hologres 資料庫中的查詢計畫
• get_hg_execution_plan：取得 Hologres 資料庫中的執行計畫
• call_hg_procedure：在 Hologres 資料庫中呼叫程序
• create_hg_maxcompute_foreign_table：在 Hologres 資料庫中建立 MaxCompute 外部表。

由於部分代理不支援資源與資源範本，因此提供下列工具來取得結構描述、資料表、檢視表及外部表的中繼資料。

• list_hg_schemas：列出目前 Hologres 資料庫中的所有結構描述，排除系統結構描述。
• list_hg_tables_in_a_schema：列出特定結構描述中的所有資料表，包含其類型（資料表、檢視表、外部表、分割區表）。
  • 參數：schema_name（字串）
• show_hg_table_ddl：顯示 Hologres 資料庫中資料表、檢視表或外部表的 DDL 腳本。
  • 參數：schema_name（字串）、table（字串）
• query_and_plotly_chart：執行 SELECT SQL 查詢並產生圖表（長條圖、折線圖、散佈圖、圓餅圖、直方圖、區域圖）。回傳查詢結果與 base64 編碼的 PNG 圖片。
  • 參數：query（字串）、chart_type（字串，預設 "bar"）、x_column（字串）、y_column（字串）、title（字串）
• analyze_hg_query_by_id：透過 hg_query_log 中的 query_id 分析特定查詢的效能概況。回傳詳細指標，包含持續時間、記憶體、CPU 時間、讀寫統計。
  • 參數：query_id（字串）
• get_hg_slow_queries：從 hg_query_log 取得依持續時間排序的慢查詢。
  • 參數：min_duration_ms（整數，預設 1000）、limit（整數，預設 20）
• list_hg_dynamic_tables：列出所有動態表及其狀態、新鮮度設定與最後重新整理資訊。
  • 參數：schema_name（字串，選用）
• get_hg_dynamic_table_refresh_history：取得特定動態表的重新整理歷史記錄，包含持續時間、狀態與延遲。
  • 參數：schema_name（字串）、table_name（字串）、limit（整數，預設 10）
• list_hg_recyclebin：列出 Hologres 資源回收筒中的所有資料表（已刪除但可還原的資料表）。
• restore_hg_table_from_recyclebin：從 Hologres 資源回收筒還原已刪除的資料表。
  • 參數：table_name（字串）、schema_name（字串，預設 "public"）
• list_hg_warehouses：列出所有運算群組（倉儲）及其 CPU、記憶體、叢集數量與狀態。
• switch_hg_warehouse：將目前工作階段的運算資源切換至指定的倉儲。
  • 參數：warehouse_name（字串）
• get_hg_table_storage_size：取得資料表的儲存空間大小詳細資訊，包含總計、資料、索引與中繼資料明細。
  • 參數：schema_name（字串）、table（字串）
• cancel_hg_query：透過處理程序 ID 取消或終止執行中的查詢。
  • 參數：pid（整數）、terminate（布林值，預設 false）
• list_hg_active_queries：從 pg_stat_activity 列出目前活躍的查詢與連線。
  • 參數：state（字串："active"、"idle" 或 "all"，預設 "active"）
• list_hg_query_queues：列出所有查詢佇列及其分類器（並行限制、路由規則）。需 V3.0+。
• get_hg_table_properties：取得資料表屬性，包含 distribution_key、clustering_key、segment_key、bitmap_columns、binlog 設定等。
  • 參數：schema_name（字串）、table（字串）
• get_hg_table_shard_info：取得資料表的 Table Group 與分片數量資訊，用於診斷資料傾斜。
  • 參數：schema_name（字串）、table（字串）
• list_hg_external_databases：列出所有外部資料庫與 Foreign Server，用於 Lakehouse 加速。需 V3.0+。
• get_hg_lock_diagnostics：透過顯示封鎖與等待中的查詢來診斷鎖定競爭。
• get_hg_table_info_trend：從 hg_table_info 取得資料表儲存趨勢，顯示每日儲存大小、檔案數量與資料列數變化。
  • 參數：schema_name（字串）、table（字串）、days（整數，預設 7）
• manage_hg_query_queue：建立、刪除或清空查詢佇列。需 V3.0+ 與超級使用者權限。
  • 參數：action（字串："create"、"drop"、"clear"）、queue_name（字串）、max_concurrency（整數，用於 create）、max_queue_size（整數，用於 create）
• manage_hg_classifier：為查詢佇列建立或刪除分類器。需 V3.0+。
  • 參數：action（字串："create"、"drop"）、queue_name（字串）、classifier_name（字串）、priority（整數，用於 create）
• set_hg_query_queue_property：設定或移除查詢佇列或分類器的屬性。需 V3.0+。
  • 參數：target（字串："queue"、"classifier"）、queue_name（字串）、property_key（字串）、property_value（字串）、classifier_name（字串，用於 classifier）、action（字串："set"、"remove"）
• manage_hg_warehouse：管理運算群組：暫停、恢復、重新啟動、重新命名或調整大小。需超級使用者權限。
  • 參數：action（字串："suspend"、"resume"、"restart"、"rename"、"resize"）、warehouse_name（字串）、cu（整數，用於 resize）、new_name（字串，用於 rename）
• get_hg_warehouse_status：取得運算群組的詳細執行狀態與擴縮進度。
  • 參數：warehouse_name（字串）
• rebalance_hg_warehouse：觸發運算群組的分片重新平衡以消除資料傾斜。
  • 參數：warehouse_name（字串）
• list_hg_data_masking_rules：列出透過 hg_anon 擴充功能設定的所有資料遮罩規則（欄位層級與使用者層級）。
• query_hg_external_files：使用 EXTERNAL_FILES 函式直接從 OSS 查詢檔案，無需建立外部表。需 V4.1+。
  • 參數：path（字串）、format（字串："csv"、"parquet"、"orc"）、columns（字串，選用）、oss_endpoint（字串，選用）、role_arn（字串，選用）
• get_hg_guc_config：取得 GUC（Grand Unified Configuration）參數的目前值。
  • 參數：guc_name（字串）

資源

內建資源

• hologres:///schemas：取得 Hologres 資料庫中的所有結構描述

資源範本

• hologres:///{schema}/tables：列出 Hologres 資料庫中某個結構描述的所有資料表

• hologres:///{schema}/{table}/partitions：列出 Hologres 資料庫中分割區表的所有分割區

• hologres:///{schema}/{table}/ddl：取得 Hologres 資料庫中的資料表 DDL

• hologres:///{schema}/{table}/statistic：顯示 Hologres 資料庫中已收集的資料表統計資訊

• system:///{+system_path}： 系統路徑包含：

  • hg_instance_version - 顯示 Hologres 執行個體版本。
  • guc_value/<guc_name> - 顯示 GUC（Grand Unified Configuration）值。
  • missing_stats_tables - 顯示缺少統計資訊的資料表。
  • stat_activity - 顯示目前執行中查詢的資訊。
  • query_log/latest/<row_limits> - 取得指定列數的近期查詢日誌歷史記錄。
  • query_log/user/<user_name>/<row_limits> - 取得特定使用者的查詢日誌歷史記錄，並可限制列數。
  • query_log/application/<application_name>/<row_limits> - 取得特定應用程式的查詢日誌歷史記錄，並可限制列數。
  • query_log/failed/<interval>/<row_limits> - 取得失敗查詢的日誌歷史記錄，包含時間間隔與指定列數。

提示

• analyze_table_performance：產生提示以分析 Hologres 中的資料表效能
• optimize_query：產生提示以最佳化 Hologres 中的 SQL 查詢
• explore_schema：產生提示以探索 Hologres 資料庫中的結構描述

測試

本專案包含完整的單元測試與整合測試。

單元測試

單元測試不需要資料庫連線，並使用模擬的相依性。測試套件包含 326 個測試案例，涵蓋：

• 工具功能與 SQL 驗證
• 資源與資源範本
• 提示產生
• 工具函式與錯誤處理
• 並行情境
• SQL 注入防護

# Run all unit tests
uv run pytest tests/unit/ -v

# Run specific test file
uv run pytest tests/unit/test_tools.py -v

# Run with coverage
uv run pytest tests/unit/ --cov=src/hologres_mcp_server --cov-report=html

整合測試

整合測試需要實際的 Hologres 資料庫連線。測試套件包含 61 個測試案例，分為 12 個測試類別：

測試類別	測試數	說明
TestMCPConnection	5	MCP 伺服器連線與基本功能
TestMCPResources	14	資源讀取功能（結構描述、資料表、DDL、統計資訊、分割區、查詢日誌）
TestMCPTools	10	唯讀操作的工具呼叫
TestMCPProcedureTools	3	預存程序的工具呼叫
TestMCPMaxComputeTools	1	MaxCompute 外部表建立
TestMCPDDLTools	5	DDL 操作（CREATE、ALTER、DROP、COMMENT）
TestMCPDMLTools	3	DML 操作（INSERT、UPDATE、DELETE）
TestErrorHandling	3	錯誤處理與邊界案例
TestMCPPrompts	4	提示產生功能
TestMCPConcurrency	3	並行 MCP 操作
TestMCPBoundaryConditions	4	邊界案例（Unicode、NULL、空結果）
TestMCPPerformance	3	效能情境（大量/寬欄位結果集）

1. 從範例建立設定檔：

cp tests/integration/.test_mcp_client_env_example tests/integration/.test_mcp_client_env

2. 使用您的 Hologres 憑證編輯設定檔：

HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com
HOLOGRES_PORT=80
HOLOGRES_USER=your_username
HOLOGRES_PASSWORD=your_password
HOLOGRES_DATABASE=your_database

3. 執行整合測試：

# Run all integration tests
uv run pytest tests/integration/ -v -m integration

# Run specific test class
uv run pytest tests/integration/test_mcp_integration.py::TestMCPTools -v

# Run all tests (unit + integration)
uv run pytest tests/ -v

注意： 若缺少 .test_mcp_client_env 檔案或其中的設定不完整，整合測試將會被跳過。

程式碼品質

本專案使用 ruff 進行程式碼檢查與格式化。

# Install dev dependencies
uv sync --dev
uv pip install ruff

# Check code style
uv run ruff check .

# Check and auto-fix
uv run ruff check . --fix

# Format code
uv run ruff format .

# Format check only (no changes)
uv run ruff format . --check

建置與發布

建置

本專案使用 hatchling 作為建置後端。建置成品將產生於 dist/ 目錄中。

# Using uv (recommended)
uv build

# Or using python build module
pip install build
python -m build

發布至 PyPI

# Install twine
pip install twine

# Upload to PyPI
twine upload dist/*

# Or upload to Test PyPI first for verification
twine upload --repository testpypi dist/*

發布工作流程

# 1. Update version in pyproject.toml
# 2. Clean old build artifacts
rm -rf dist/

# 3. Build
uv build

# 4. Publish
twine upload dist/*

# 5. Tag the release
git tag -a v1.0.3 -m "Release v1.0.3"
git push origin v1.0.3

更新 CLI 功能

# Use FastMCP framework to generate CLI code and Skill
uv run fastmcp generate-cli hologres-mcp-server hologres_mcp_cli/hologres_mcp_cli.py -f