Hologres MCP Server

What is Hologres MCP Server about?

Hologres MCP Server acts as a bridge between AI agents and Hologres databases, exposing a set of tools and resource templates that allow agents to query schema information, execute SQL statements, collect statistics, and retrieve execution plans.

How to use Hologres MCP Server?

1. Installation
   • Local source mode: Clone the repository and run the server with UV.

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

   • PIP mode: Install the package from PyPI and launch it via UV or UVX.

     pip install hologres-mcp-server
     # Using uv
     uv run --with hologres-mcp-server hologres-mcp-server
     # Or using uvx (single‑command mode)
     uvx hologres-mcp-server
     

2. Configuration Add a server entry to the MCP client configuration file, supplying connection details through environment variables (HOLOGRES_HOST, HOLOGRES_PORT, HOLOGRES_USER, HOLOGRES_PASSWORD, HOLOGRES_DATABASE).

Key Features

• Execution tools for SELECT, DML, DDL, and stored procedures.
• Statistics collection and query‑plan retrieval.
• Metadata utilities: list schemas, list tables in a schema, show table DDL.
• Resource templates for convenient URI‑based access (e.g., hologres:///{schema}/tables).
• Built‑in system resources for instance version, GUC values, missing statistics, activity monitoring, and query log queries.

Use Cases

• AI‑driven data exploration: Agents can automatically discover database structure and run ad‑hoc queries.
• Automated reporting: Generate and execute SQL reports without hard‑coding connection logic.
• Performance tuning: Retrieve execution plans and table statistics to suggest optimizations.
• Procedural automation: Invoke stored procedures from conversational agents.

FAQ

• Do I need a Hologres instance? Yes, the server connects to an existing Hologres database using the provided host, port, user, password, and database name.
• Can I run the server in a container? Absolutely; the package is pure Python and can be executed in any container that has Python 3.9+ and the required environment variables.
• What if I only need metadata access? Use the list_hg_* and show_hg_table_ddl tools or the corresponding hologres:// resource URIs.
• Is authentication handled by the server? The server forwards the credentials you set in the environment to Hologres; no additional authentication layer is added.
• How do I update the server? Re‑install the package via pip install --upgrade hologres-mcp-server or pull the latest code from the GitHub repository.

English | 中文

Hologres MCP Server

Hologres MCP Server serves as a universal interface between AI Agents and Hologres databases. It enables seamless communication between AI Agents and Hologres, helping AI Agents retrieve Hologres database metadata and execute SQL operations.

Configuration

Mode 1: Using Local File

Download

Download from Github

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

MCP Integration

Add the following configuration to the MCP client configuration file:

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

Mode 2: Using PIP Mode

Installation

Install MCP Server using the following package:

pip install hologres-mcp-server

MCP Integration

Add the following configuration to the MCP client configuration file:

Use uv mode

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

Use uvx mode

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

Components

Tools

• execute_hg_select_sql: Execute a SELECT SQL query in Hologres database
• execute_hg_select_sql_with_serverless: Execute a SELECT SQL query in Hologres database with serverless computing
• execute_hg_dml_sql: Execute a DML (INSERT, UPDATE, DELETE) SQL query in Hologres database
• execute_hg_ddl_sql: Execute a DDL (CREATE, ALTER, DROP, COMMENT ON) SQL query in Hologres database
• gather_hg_table_statistics: Collect table statistics in Hologres database
• get_hg_query_plan: Get query plan in Hologres database
• get_hg_execution_plan: Get execution plan in Hologres database
• call_hg_procedure: Invoke a procedure in Hologres database
• create_hg_maxcompute_foreign_table: Create MaxCompute foreign tables in Hologres database.

Since some Agents do not support resources and resource templates, the following tools are provided to obtain the metadata of schemas, tables, views, and external tables.

• list_hg_schemas: Lists all schemas in the current Hologres database, excluding system schemas.
• list_hg_tables_in_a_schema: Lists all tables in a specific schema, including their types (table, view, external table, partitioned table).
• show_hg_table_ddl: Show the DDL script of a table, view, or external table in the Hologres database.

Resources

Built-in Resources

• hologres:///schemas: Get all schemas in Hologres database

Resource Templates

• hologres:///{schema}/tables: List all tables in a schema in Hologres database

• hologres:///{schema}/{table}/partitions: List all partitions of a partitioned table in Hologres database

• hologres:///{schema}/{table}/ddl: Get table DDL in Hologres database

• hologres:///{schema}/{table}/statistic: Show collected table statistics in Hologres database

• system:///{+system_path}: System paths include:

  • hg_instance_version - Shows the hologres instance version.
  • guc_value/<guc_name> - Shows the guc (Grand Unified Configuration) value.
  • missing_stats_tables - Shows the tables that are missing statistics.
  • stat_activity - Shows the information of current running queries.
  • query_log/latest/<row_limits> - Get recent query log history with specified number of rows.
  • query_log/user/<user_name>/<row_limits> - Get query log history for a specific user with row limits.
  • query_log/application/<application_name>/<row_limits> - Get query log history for a specific application with row limits.
  • query_log/failed/<interval>/<row_limits> - Get failed query log history with interval and specified number of rows.

Prompts

None at this time