impala-mcp-server
Provides safe, read-only access to Apache Impala clusters, enabling SQL queries, catalog and metadata exploration, table statistics, partition/column details, cluster overview, and analysis prompt templates.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@impala-mcp-server show me the schema of the customers table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
impala-mcp-server
An Apache Impala Model Context Protocol (MCP) server, modeled after apache/doris-mcp-server. It gives AI agents (Claude, Cursor, Cline, Dify, ...) safe, read-only access to an Impala cluster: SQL queries, catalog/metadata exploration, table statistics, cluster overview, and analysis prompt templates.
AI agent ──MCP──▶ impala-mcp-server ──HiveServer2 (impyla)──▶ Apache ImpalaFeatures
17 read-only tools with Doris-MCP-compatible flat naming (
get_db_list,get_table_schema,get_table_preview, ...) plus Impala-specific ones (get_partitions,get_column_stats,get_slow_query_records, ...).Read-only SQL guard: only
SELECT/SHOW/DESCRIBE/EXPLAIN/WITH ... SELECT/ bareSETare allowed; DDL/DML keywords, multi-statement injection, and session mutation (SET x=y) are rejected. Identifier validation + backtick quoting for every tool-built statement.4 MCP resources:
impala://databases, per-database tables, table schemas, cluster overview.9 prompt templates for common analysis workflows (data exploration, join analysis, performance tuning, slow-query hunting, data quality, reporting, DDL drafting).
Transports:
stdio(local MCP clients) and Streamable HTTP (http://host:3000/mcpwith/liveand/readyprobes).Enterprise connectivity: NOSASL / PLAIN / LDAP / Kerberos (GSSAPI), TLS, HiveServer2-over-HTTP (Knox), configurable query timeout (
SET QUERY_TIMEOUT_S) and a small thread-safe connection pool.Lazy connections: startup never touches Impala; tools return graceful JSON errors when the cluster is unreachable.
Related MCP server: Cloudera Iceberg MCP Server
Tool list
Tool | Impala statement | Purpose |
| (any read-only SQL) | Execute SELECT / SHOW / DESCRIBE / EXPLAIN / WITH / bare SET |
|
| Execution plan of a query |
|
| Current session query options |
|
| List databases |
|
| Tables/views of a database |
|
| Columns, types, comments, partition columns |
|
| Table-level comment |
|
| Full CREATE TABLE statement |
|
| First rows of a table (n ≤ 1000) |
|
| Built-in + UDF functions |
|
| Rows / files / bytes totals |
|
| Distinct values, nulls, avg size |
|
| Partition list with per-partition stats |
| mixed | Table/view counts + aggregated sizes per database |
|
| Connectivity, latency, version |
|
| Version, hosts, database list |
|
| Recent/slow queries (Impala 4.2+ workload management) |
Every tool returns a JSON string: {"status": "success", "data": ...} or {"status": "error", "error": {"type", "message", "hint"}}.
Doris parity: the tool names deliberately mirror doris-mcp-server's flat API (
get_db_list,get_db_table_list,get_table_schema,get_table_comment,get_ddl,get_table_preview,get_table_size,get_db_metadata_summary,get_health_check,get_cluster_overview, ...), so agents configured for the Doris server adapt with minimal prompt changes.
Installation
Requires Python 3.10+.
# from source
git clone <this-repo> && cd impala-mcp-server
pip install -e .
# with test dependencies
pip install -e ".[dev]"Configuration
Environment variables (a .env file is loaded automatically; see .env.example):
Variable | Default | Description |
|
| Impala coordinator (impalad) host |
|
| HiveServer2 port |
|
| Default database context |
| — | Credentials (PLAIN / LDAP) |
|
|
|
|
| For GSSAPI |
|
| TLS settings |
|
| HS2-over-HTTP (Knox) |
|
| Socket connect timeout (s) |
|
| Server-side query timeout via |
|
| Pool size |
|
| Recycle connections older than this (s) |
|
| Source for slow-query tool |
|
| Read-only guard master switch |
| DDL/DML list | Comma-separated override |
|
| Dangerous: allow DDL/DML through |
|
| Hard row cap |
|
| Default cap for |
|
|
|
|
| HTTP bind address |
|
| Logging (stderr for stdio) |
Usage
# stdio (Claude Code / Cursor / Cline ...)
impala-mcp-server
# Streamable HTTP
impala-mcp-server --transport http --host 0.0.0.0 --port 3000
# MCP endpoint: POST /mcp
# Liveness: GET /live
# Readiness: GET /ready (pings Impala)Claude Desktop / Cursor config
{
"mcpServers": {
"impala": {
"command": "impala-mcp-server",
"env": {
"IMPALA_HOST": "impala-coordinator.example.com",
"IMPALA_PORT": "21050",
"IMPALA_AUTH_MECHANISM": "LDAP",
"IMPALA_USER": "analyst",
"IMPALA_PASSWORD": "secret"
}
}
}
}Streamable HTTP (Dify / LangChain / custom hosts)
{
"mcpServers": {
"impala": {
"url": "http://127.0.0.1:3000/mcp"
}
}
}Security notes
The server is read-only by design.
ALLOW_WRITE_SQL=truedisables the guard entirely — prefer leaving it off and granting a read-only Impala role.All identifiers supplied to tools are validated and backtick-quoted; LIKE patterns are literal-escaped.
Statements are checked one-by-one after stripping comments and string literals, so
SELECT 'DROP TABLE x'passes whileWITH cte AS (...) INSERT ...is blocked.HTTP transport binds to loopback by default; put an authenticating proxy in front for remote use (the MCP server itself does not add auth).
The slow-query tool only reads the system query log table; it requires workload management to be enabled cluster-side.
Docker
docker build -t impala-mcp-server .
docker run --rm -e IMPALA_HOST=coordinator.example.com -p 3000:3000 \
impala-mcp-server --transport http --host 0.0.0.0Development
pip install -e ".[dev]"
pytest # 93 tests, no live Impala requiredLayout (mirrors doris-mcp-server):
impala_mcp_server/
├── main.py # argparse, FastMCP assembly, transports, health probes
└── utils/
├── config.py # dataclass config from IMPALA_* env vars
├── db.py # impyla wrapper: pool, execution, JSON-safe serialization
├── sql_security.py # identifier validation, read-only SQL guard
├── tools.py # 17 MCP tools + registration
└── prompts.py # 9 prompt templatesLicense
Apache License 2.0. This project is not affiliated with the Apache Software Foundation; "Apache Impala" is a trademark of the ASF.
Available Tools
17 toolsexplain_queryARead-onlyIdempotent
Return the Impala execution plan (EXPLAIN) for a SELECT or WITH query.
Inputs: sql (required). Returns: result
get_cluster_overviewARead-onlyIdempotent
Cluster snapshot: Impala version, current database, database list and impalad hosts (SHOW HOSTS).
Inputs: no named parameters. Returns: result
get_column_statsARead-onlyIdempotent
Column-level statistics: distinct values, nulls, max/avg size (SHOW COLUMN STATS).
Inputs: db_name (required), table_name (required). Returns: result
get_db_listARead-onlyIdempotent
List all databases visible to the configured Impala user, optionally filtered by a SQL LIKE pattern.
Inputs: pattern. Returns: result
get_db_metadata_summaryARead-onlyIdempotent
Summarize a database: table/view counts plus aggregated rows/files/bytes sampled over up to max_tables tables.
Inputs: db_name, max_tables, include_table_stats. Returns: result
get_db_table_listARead-onlyIdempotent
List tables and views of a database (SHOW TABLES IN db). Omit db_name to use the server default database; pattern filters with SQL LIKE.
Inputs: db_name, pattern. Returns: result
get_ddlARead-onlyIdempotent
Return the full CREATE TABLE statement (SHOW CREATE TABLE) including partitions, storage format and properties.
Inputs: db_name (required), table_name (required). Returns: result
get_functionsARead-onlyIdempotent
List built-in and user-defined functions of a database (SHOW FUNCTIONS), optionally filtered by a LIKE pattern.
Inputs: db_name, pattern. Returns: result
get_health_checkARead-onlyIdempotent
Check Impala connectivity: SELECT 1 round-trip latency and server version.
Inputs: no named parameters. Returns: result
get_partitionsARead-onlyIdempotent
List partitions with per-partition statistics (SHOW PARTITIONS). Only valid for partitioned tables.
Inputs: db_name (required), table_name (required). Returns: result
get_session_optionsARead-onlyIdempotent
List current Impala session query options (SET).
Inputs: no named parameters. Returns: result
get_slow_query_recordsARead-onlyIdempotent
Recent/slow queries from the Impala workload-management query log (sys.impala_query_log by default; needs Impala 4.2+ / CDP). Filter by time_range_hours or min_duration_ms.
Inputs: limit, min_duration_ms, time_range_hours. Returns: result
get_table_commentBRead-onlyIdempotent
Return the table-level comment parsed from SHOW CREATE TABLE.
Inputs: db_name (required), table_name (required). Returns: result
get_table_previewARead-onlyIdempotent
Preview the first rows of a table (SELECT * ... LIMIT n, n<=1000).
Inputs: db_name (required), table_name (required), limit. Returns: result
get_table_schemaBRead-onlyIdempotent
Describe a table: column names, data types, comments and partition columns (DESCRIBE table).
Inputs: db_name (required), table_name (required). Returns: result
get_table_sizeBRead-onlyIdempotent
Physical table statistics: row count, number of files and total bytes (SHOW TABLE STATS). Values are -1 until COMPUTE STATS has been run.
Inputs: db_name (required), table_name (required). Returns: result
queryARead-onlyIdempotent
Execute a read-only SQL statement (SELECT / SHOW / DESCRIBE / EXPLAIN / WITH ... SELECT / bare SET) against Apache Impala and return columns+rows. DDL/DML is blocked unless the server runs with ALLOW_WRITE_SQL=true.
Inputs: sql (required), max_rows. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool targets a clearly distinct resource or action: query execution, plan explanation, session options, and a comprehensive set of metadata inspectors for databases, tables, schemas, DDL, stats, partitions, and cluster health. Even similar-sounding tools like get_table_schema, get_table_comment, and get_ddl are cleanly separated by their descriptions.
The vast majority of tools follow a consistent lower_snake_case get_* pattern with clear noun targets. The exceptions are the bare `query` tool and `explain_query`, which are still readable but deviate slightly from the dominant get_ prefix convention.
At 17 tools, the server is slightly above the typical 3–15 range, but the count is justified by the broad scope of Impala metadata and query functionality. Each tool addresses a distinct need, so the set does not feel bloated.
The tool set covers the full envelope of read-only Impala interaction: arbitrary queries, execution plans, session settings, database/table listing, schema inspection, DDL retrieval, data previews, functions, table and column statistics, partitions, cluster overview, and slow-query logs. There are no obvious dead ends or major missing operations for its intended read-only/metadata-analysis purpose.
Maintenance
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables read-only access to Apache Iceberg tables via Impala, allowing LLMs to inspect database schemas and execute SQL queries to retrieve data from Iceberg tables.213Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Iceberg tables via Apache Impala, enabling LLMs to inspect database schemas and execute SQL queries on Iceberg data.Apache 2.0
- FlicenseAqualityDmaintenanceEnables LLM agents to query and explore Cloudera Hive virtual warehouses through tools like list_databases, list_tables, describe_table, get_table_sample, and execute_query with read-only safety.5-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to inspect schemas, analyze performance, check security, and troubleshoot SQL Server 2019+ databases through a safe, controlled interface.-