Hologres MCP Server: Metadata, Query and Analysis

Overview

Hologres MCP Server is an MCP (Model Context Protocol) adapter that exposes Hologres databases to AI agents and developer tools. It provides a consistent interface for discovering schema metadata, running SQL (SELECT/DML/DDL), collecting table statistics, and obtaining query and execution plans. By acting as the bridge between an AI agent and Hologres, the server enables programmatic inspection and analysis of data for rapid insights and automated data-management workflows.

This server is useful when you want AI assistants to reason about your Hologres data — for example, to suggest query optimizations, diagnose slow queries, or generate summaries based on table contents — while keeping credentials and logic centralized. It can be run from source, installed as a Python package, and integrated into MCP-enabled clients (uv/uvx or tools like Claude Code).

Features

• Connects AI agents to Hologres for metadata discovery and SQL execution
• Execute SELECT (including serverless), DML and DDL statements
• Retrieve query and execution plans for performance analysis
• Collect and surface table statistics for query optimization
• Built-in resource templates to fetch schemas, table lists, DDL, partitions and stats
• Prompts and helper tools to generate analysis/optimization guidance
• Integration options: local repository, pip package, or uv/uvx runner

Installation / Configuration

Clone the repository:

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

Install from PyPI:

pip install hologres-mcp-server

Environment variables required by the server:

• HOLOGRES_HOST — Hologres host
• HOLOGRES_PORT — Hologres port (numeric)
• HOLOGRES_USER — access id / username
• HOLOGRES_PASSWORD — access key / password
• HOLOGRES_DATABASE — target database name

Example MCP client configuration (local directory mode, uv runner):

{
  "mcpServers": {
    "hologres-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/alibabacloud-hologres-mcp-server",
        "run",
        "hologres-mcp-server"
      ],
      "env": {
        "HOLOGRES_HOST": "your_host",
        "HOLOGRES_PORT": "your_port",
        "HOLOGRES_USER": "your_user",
        "HOLOGRES_PASSWORD": "your_password",
        "HOLOGRES_DATABASE": "your_database"
      }
    }
  }
}

Example MCP client configuration (pip package, uvx runner):

{
  "mcpServers": {
    "hologres-mcp-server": {
      "command": "uvx",
      "args": [
        "hologres-mcp-server"
      ],
      "env": {
        "HOLOGRES_HOST": "your_host",
        "HOLOGRES_PORT": "your_port",
        "HOLOGRES_USER": "your_user",
        "HOLOGRES_PASSWORD": "your_password",
        "HOLOGRES_DATABASE": "your_database"
      }
    }
  }
}

Add to Claude Code (example):

claude mcp add hologres-mcp-server \
  -e HOLOGRES_HOST=<host> \
  -e HOLOGRES_PORT=<port> \
  -e HOLOGRES_USER=<user> \
  -e HOLOGRES_PASSWORD=<password> \
  -e HOLOGRES_DATABASE=<database> \
  -- uvx hologres-mcp-server

Available Tools

Key tools exposed by the MCP server (name, purpose, primary parameters):

Metadata helpers (for agents that don’t use resources):

Available Resources

Resource endpoints and templates provided by the server:

• Built-in: hologres:///schemas — get schema list
• Templates:
  • hologres:///{schema}/tables — list tables in a schema
  • hologres:///{schema}/{table}/ddl — get table DDL
  • hologres:///{schema}/{table}/statistic — get collected stats
  • hologres:///{schema}/{table}/partitions — list partitions (partitioned tables)
• System paths (system:///…):
  • hg_instance_version, guc_value/<guc_name>
  • missing_stats_tables, stat_activity
  • query_log/latest/, query_log/user//, query_log/failed//

    Use Cases

    • Inspect schema and table structure before building queries:
      • Use list_hg_schemas → list_hg_tables_in_a_schema → show_hg_table_ddl to programmatically construct safe queries.
    • Run and debug queries:
      • execute_hg_select_sql to fetch results for analysis; get_hg_query_plan and get_hg_execution_plan to diagnose slow queries and suggest optimizations.
    • Automated performance tuning:
      • gather_hg_table_statistics to refresh statistics, then re-run planner to compare improved plans.
    • Data management and DDL automation:
      • execute_hg_ddl_sql to create/alter tables or create_hg_maxcompute_foreign_table to integrate MaxCompute datasets.
    • Integrating with AI assistants:
      • Expose these tools to an AI agent (via MCP) so it can answer natural language questions about your data, propose query improvements, or generate summaries.

    Testing and Reliability

    The project includes unit and integration tests. Unit tests use mocked dependencies and cover SQL validation, tool behaviors and resource handling. This improves confidence before deploying the MCP server in production environments.

    For the source, examples, and full reference, see the repository on GitHub:

    Tags:developer-tools