Skip to main content
Glama
impala-mcp-server

impala-mcp-server

by yaowenqiang

impala-mcp-server

English | 简体中文

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 Impala

Features

  • 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 / bare SET are 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/mcp with /live and /ready probes).

  • 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

query

(any read-only SQL)

Execute SELECT / SHOW / DESCRIBE / EXPLAIN / WITH / bare SET

explain_query

EXPLAIN ...

Execution plan of a query

get_session_options

SET

Current session query options

get_db_list

SHOW DATABASES [LIKE p]

List databases

get_db_table_list

SHOW TABLES IN db [LIKE p]

Tables/views of a database

get_table_schema

DESCRIBE db.t

Columns, types, comments, partition columns

get_table_comment

SHOW CREATE TABLE (parsed)

Table-level comment

get_ddl

SHOW CREATE TABLE db.t

Full CREATE TABLE statement

get_table_preview

SELECT * ... LIMIT n

First rows of a table (n ≤ 1000)

get_functions

SHOW FUNCTIONS IN db

Built-in + UDF functions

get_table_size

SHOW TABLE STATS

Rows / files / bytes totals

get_column_stats

SHOW COLUMN STATS

Distinct values, nulls, avg size

get_partitions

SHOW PARTITIONS

Partition list with per-partition stats

get_db_metadata_summary

mixed

Table/view counts + aggregated sizes per database

get_health_check

SELECT 1, VERSION()

Connectivity, latency, version

get_cluster_overview

SHOW HOSTS, VERSION()

Version, hosts, database list

get_slow_query_records

sys.impala_query_log

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_HOST

localhost

Impala coordinator (impalad) host

IMPALA_PORT

21050

HiveServer2 port

IMPALA_DATABASE

default

Default database context

IMPALA_USER / IMPALA_PASSWORD

—

Credentials (PLAIN / LDAP)

IMPALA_AUTH_MECHANISM

NOSASL

NOSASL / PLAIN / LDAP / GSSAPI

IMPALA_KERBEROS_SERVICE_NAME

impala

For GSSAPI

IMPALA_USE_SSL / IMPALA_CA_CERT

false / —

TLS settings

IMPALA_USE_HTTP_TRANSPORT / IMPALA_HTTP_PATH

false / —

HS2-over-HTTP (Knox)

IMPALA_CONNECTION_TIMEOUT

30

Socket connect timeout (s)

IMPALA_QUERY_TIMEOUT

300

Server-side query timeout via SET QUERY_TIMEOUT_S

IMPALA_MAX_CONNECTIONS

10

Pool size

IMPALA_MAX_CONNECTION_AGE

3600

Recycle connections older than this (s)

IMPALA_QUERY_LOG_TABLE

sys.impala_query_log

Source for slow-query tool

ENABLE_SECURITY_CHECK

true

Read-only guard master switch

BLOCKED_KEYWORDS

DDL/DML list

Comma-separated override

ALLOW_WRITE_SQL

false

Dangerous: allow DDL/DML through query

MAX_RESULT_ROWS

10000

Hard row cap

DEFAULT_RESULT_ROWS

1000

Default cap for query

MCP_TRANSPORT

stdio

stdio or http

MCP_HOST / MCP_PORT

localhost / 3000

HTTP bind address

LOG_LEVEL / LOG_FILE_PATH

INFO / —

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=true disables 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 while WITH 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.0

Development

pip install -e ".[dev]"
pytest            # 93 tests, no live Impala required

Layout (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 templates

License

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 tools
explain_queryA
Read-onlyIdempotent

Return the Impala execution plan (EXPLAIN) for a SELECT or WITH query.

Inputs: sql (required). Returns: result

get_cluster_overviewA
Read-onlyIdempotent

Cluster snapshot: Impala version, current database, database list and impalad hosts (SHOW HOSTS).

Inputs: no named parameters. Returns: result

get_column_statsA
Read-onlyIdempotent

Column-level statistics: distinct values, nulls, max/avg size (SHOW COLUMN STATS).

Inputs: db_name (required), table_name (required). Returns: result

get_db_listA
Read-onlyIdempotent

List all databases visible to the configured Impala user, optionally filtered by a SQL LIKE pattern.

Inputs: pattern. Returns: result

get_db_metadata_summaryA
Read-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_listA
Read-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_ddlA
Read-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_functionsA
Read-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_checkA
Read-onlyIdempotent

Check Impala connectivity: SELECT 1 round-trip latency and server version.

Inputs: no named parameters. Returns: result

get_partitionsA
Read-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_optionsA
Read-onlyIdempotent

List current Impala session query options (SET).

Inputs: no named parameters. Returns: result

get_slow_query_recordsA
Read-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_commentB
Read-onlyIdempotent

Return the table-level comment parsed from SHOW CREATE TABLE.

Inputs: db_name (required), table_name (required). Returns: result

get_table_previewA
Read-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_schemaB
Read-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_sizeB
Read-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

queryA
Read-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

    A3.9/5.0

    Scored across 17 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      2
      13
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      Enables 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
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to inspect schemas, analyze performance, check security, and troubleshoot SQL Server 2019+ databases through a safe, controlled interface.
      -