Hologres MCP Server

English | 中文

Hologres MCP 服务

Hologres MCP 服务是 AI Agent 与 Hologres 数据库之间的通用接口。它支持 AI Agent 与 Hologres 无缝通信，帮助 AI Agent 获取 Hologres 数据库元数据并执行 SQL 操作。

配置

模式 1：使用本地文件

下载

从 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"
            }
        }
    }
}

模式 2：使用 PIP 模式

安装

使用以下软件包安装 MCP 服务：

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"
            }
        }
    }
}

模式 3：使用 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（string）、table（string）
• get_hg_query_plan：获取 Hologres 数据库中的查询计划
• get_hg_execution_plan：获取 Hologres 数据库中的执行计划
• call_hg_procedure：调用 Hologres 数据库中的过程
• create_hg_maxcompute_foreign_table：在 Hologres 数据库中创建 MaxCompute 外部表。 由于部分 Agent 不支持资源和资源模板，因此提供以下工具，用于获取模式、表、视图和外部表的元数据。
• list_hg_schemas：列出当前 Hologres 数据库中的所有模式，不包括系统模式。
• list_hg_tables_in_a_schema：列出指定模式中的所有表，包括其类型（表、视图、外部表、分区表）。
  • 参数：schema_name（string）
• show_hg_table_ddl：显示 Hologres 数据库中表、视图或外部表的 DDL 脚本。
  • 参数：schema_name（string）、table（string）
• query_and_plotly_chart：执行 SELECT SQL 查询并生成图表（柱状图、折线图、散点图、饼图、直方图、面积图）。返回查询结果和 Base64 编码的 PNG 图像。
  • 参数：query（string）、chart_type（string，默认值为 "bar"）、x_column（string）、y_column（string）、title（string）
• analyze_hg_query_by_id：根据 hg_query_log 中的 query_id 分析指定查询的性能配置文件。返回详细指标，包括耗时、内存、CPU 时间以及读写统计信息。
  • 参数：query_id（string）
• get_hg_slow_queries：从 hg_query_log 中获取慢查询，并按耗时排序。
  • 参数：min_duration_ms（int，默认值为 1000）、limit（int，默认值为 20）
• list_hg_dynamic_tables：列出所有动态表及其状态、新鲜度设置和上次刷新信息。
  • 参数：schema_name（string，可选）
• get_hg_dynamic_table_refresh_history：获取指定动态表的刷新历史，包括耗时、状态和延迟。
  • 参数：schema_name（string）、table_name（string）、limit（int，默认值为 10）
• list_hg_recyclebin：列出 Hologres 回收站中的所有表（可恢复的已删除表）。
• restore_hg_table_from_recyclebin：从 Hologres 回收站恢复已删除的表。
  • 参数：table_name（string）、schema_name（string，默认值为 "public"）
• list_hg_warehouses：列出所有计算组（仓库）及其 CPU、内存、集群数量和状态。
• switch_hg_warehouse：将当前会话的计算资源切换到指定仓库。
  • 参数：warehouse_name（string）
• get_hg_table_storage_size：获取表的存储大小详情，包括总量、数据、索引和元数据的细分信息。
  • 参数：schema_name（string）、table（string）
• cancel_hg_query：根据进程 ID 取消或终止正在运行的查询。
  • 参数：pid（int）、terminate（bool，默认值为 false）
• list_hg_active_queries：从 pg_stat_activity 列出当前活动的查询和连接。
  • 参数：state（string："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（string）、table（string）
• get_hg_table_shard_info：获取表的表组和分片数量信息，用于诊断数据倾斜。
  • 参数：schema_name（string）、table（string）
• list_hg_external_databases：列出所有用于湖仓加速的外部数据库和外部服务器。需要 V3.0+。
• get_hg_lock_diagnostics：通过显示阻塞和等待中的查询来诊断锁竞争。
• get_hg_table_info_trend：从 hg_table_info 获取表存储趋势，显示每日存储大小、文件数量和行数变化。
  • 参数：schema_name（string）、table（string）、days（int，默认值为 7）
• manage_hg_query_queue：创建、删除或清空查询队列。需要 V3.0+ 和超级用户权限。
  • 参数：action（string："create"、"drop"、"clear"）、queue_name（string）、max_concurrency（int，用于 create）、max_queue_size（int，用于 create）
• manage_hg_classifier：为查询队列创建或删除分类器。需要 V3.0+。
  • 参数：action（string："create"、"drop"）、queue_name（string）、classifier_name（string）、priority（int，用于 create）
• set_hg_query_queue_property：设置或移除查询队列或分类器的属性。需要 V3.0+。
  • 参数：target（string："queue"、"classifier"）、queue_name（string）、property_key（string）、property_value（string）、classifier_name（string，用于 classifier）、action（string："set"、"remove"）
• manage_hg_warehouse：管理计算组：暂停、恢复、重启、重命名或调整大小。需要超级用户权限。
  • 参数：action（string："suspend"、"resume"、"restart"、"rename"、"resize"）、warehouse_name（string）、cu（int，用于 resize）、new_name（string，用于 rename）
• get_hg_warehouse_status：获取计算组的详细运行状态和扩缩容进度。
  • 参数：warehouse_name（string）
• rebalance_hg_warehouse：触发计算组的分片再平衡，以消除数据倾斜。
  • 参数：warehouse_name（string）
• list_hg_data_masking_rules：列出通过 hg_anon 扩展配置的所有数据脱敏规则（列级和用户级）。
• query_hg_external_files：使用 EXTERNAL_FILES 函数直接查询 OSS 中的文件，无需创建外部表。需要 V4.1+。
  • 参数：path（string）、format（string："csv"、"parquet"、"orc"）、columns（string，可选）、oss_endpoint（string，可选）、role_arn（string，可选）
• get_hg_guc_config：获取 GUC（Grand Unified Configuration）参数的当前值。
  • 参数：guc_name（string）

资源

内置资源

• hologres:///schemas：获取 Hologres 数据库中的所有 schema

资源模板

• hologres:///{schema}/tables：列出 Hologres 数据库中某个 schema 下的所有表

• 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 数据库中某个 schema 的提示词

测试

该项目包含全面的单元测试和集成测试。

单元测试

单元测试不需要数据库连接，并使用模拟依赖项。测试套件包含 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	资源读取功能（schema、表、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