Hologres

简体中文 | English

Hologres MCP Server

Hologres MCP Server 是 AI Agent 与 Hologres 数据库之间的通用接口，支持 AI Agent 与 Hologres 无缝通信，帮助 AI Agent 获取 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：使用 Serverless Computing 在 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 外部表。

由于部分 Agent 不支持资源和资源模板，提供以下工具用于获取 Schema、表、视图和外部表的元数据。

• list_hg_schemas：列出当前 Hologres 数据库中的所有 Schema（不包括系统 Schema）。
• list_hg_tables_in_a_schema：列出指定 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：列出所有计算组（Warehouse）及其 CPU、内存、集群数量和状态。
• switch_hg_warehouse：将当前会话的计算资源切换到指定的 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 和 Shard 数量信息，用于诊断数据倾斜。
  • 参数：schema_name（字符串）、table（字符串）
• list_hg_external_databases：列出所有外部数据库和外部服务器，用于 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（整数，用于创建）、max_queue_size（整数，用于创建）
• manage_hg_classifier：为查询队列创建或删除分类器。需要 V3.0+。
  • 参数：action（字符串："create"、"drop"）、queue_name（字符串）、classifier_name（字符串）、priority（整数，用于创建）
• set_hg_query_queue_property：设置或移除查询队列或分类器的属性。需要 V3.0+。
  • 参数：target（字符串："queue"、"classifier"）、queue_name（字符串）、property_key（字符串）、property_value（字符串）、classifier_name（字符串，用于分类器）、action（字符串："set"、"remove"）
• manage_hg_warehouse：管理计算组：挂起、恢复、重启、重命名或调整大小。需要超级用户权限。
  • 参数：action（字符串："suspend"、"resume"、"restart"、"rename"、"resize"）、warehouse_name（字符串）、cu（整数，用于调整大小）、new_name（字符串，用于重命名）
• get_hg_warehouse_status：获取计算组的详细运行状态和扩缩容进度。
  • 参数：warehouse_name（字符串）
• rebalance_hg_warehouse：触发计算组的 Shard 再平衡以消除数据倾斜。
  • 参数：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 数据库中的所有 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