alibabacloud-hologres-mcp-server

Hologres MCP Server is an MCP (Model Context Protocol) server open-sourced by Alibaba Cloud, designed to provide a general-purpose interface between AI agents and the Hologres database. Through this server, AI agents can seamlessly connect to Hologres, retrieve database metadata, and execute SQL operations.

Key Capabilities

The server provides a series of tools covering database operations, metadata queries, performance monitoring, and resource management:

• SQL Execution: Supports executing SELECT queries (including serverless computing mode), DML (INSERT, UPDATE, DELETE), and DDL (CREATE, ALTER, DROP, COMMENT ON) statements.
• Metadata Queries: List all schemas, all tables under a schema (including tables, views, foreign tables, partitioned tables), display table DDL, obtain table properties (distribution key, clustering key, segment key, bitmap columns, binlog settings, etc.), obtain table shard information, list foreign databases and foreign servers.
• Performance Analysis and Optimization: Collect table statistics, obtain query plans and execution plans, analyze query performance by query_id, obtain slow queries, diagnose lock contention, obtain table storage trends, obtain GUC configuration values.
• Data Visualization: Execute SELECT queries and generate charts (bar chart, line chart, scatter chart, pie chart, histogram, area chart), returning query results and base64-encoded PNG images.
• Dynamic Table Management: List dynamic tables and their status, freshness settings, and last refresh information, obtain dynamic table refresh history.
• Recycle Bin Management: List tables in the recycle bin, restore deleted tables from the recycle bin.
• Compute Group Management: List all compute groups (warehouses) and their CPU, memory, cluster count, and status, switch the compute resources of the current session, manage compute groups (suspend, resume, restart, rename, resize), obtain compute group status, trigger shard rebalancing.
• Query Management: Cancel or terminate running queries, list currently active queries and connections, list query queues and their classifiers, manage query queues and classifiers, set query queue properties.
• Other: List data masking rules, directly query external files on OSS (without creating foreign tables), call stored procedures, create MaxCompute foreign tables.

In addition, the serviceThe server also provides resource templates, such as getting all schemas, listing tables under a schema, listing partitions of a partitioned table, getting table DDL, displaying table statistics, as well as system path resources, such as instance version, GUC values, tables with missing statistics, information about currently running queries, query log history, etc.

The server also provides prompt generation capabilities, including analyzing table performance, optimizing SQL queries, and exploring schemas.

Usage

The server supports three deployment modes:

1. Local file mode: After downloading from GitHub, add the configuration to the MCP client configuration file.
2. PIP mode: Use pip to install the MCP Server package.
3. Streamable HTTP transport mode: Suitable for remote deployment scenarios where STDIO cannot be used. Before starting, set the Hologres connection environment variables, then start the server, and the MCP endpoint will be located at http://<host>:<port>/mcp.

The server can be used with MCP clients such as Claude Code.

Applicable scenarios

• When AI agents need to access and operate the Hologres database.
• Scenarios that require database querying, analysis, and management through natural language or AI assistance.
• Scenarios that require automated database monitoring, performance optimization, and resource management.

Limitations

• Some features require Hologres V3.0+ or V4.1+ version support, such as query queue management, external database listing, external file querying, etc.
• Operations such as managing query queues and compute groups require superuser privileges.
• Integration tests require a real Hologres database connection, and will be skipped when the configuration file is missing.

Development and testing

The project includes comprehensive unit tests and integration tests. Unit tests do not require a database connection and use mock dependencies, including 326 test cases, covering tool functionality, SQL validation, resources and resource templates, prompt generation, utility functions and error handling, concurrency scenarios, SQL injection protection, etc. Integration tests require a real Hologres database connection, including 61 test cases, divided into 12 test classes. The project uses ruff for code checking and formatting, uses hatchling as the build backend, and build artifacts are generated in the dist/ directory.