# impala-mcp-server

[English](README.md) | [简体中文](README.zh-CN.md)

An **Apache Impala** [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, modeled after [apache/doris-mcp-server](https://github.com/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.

```text
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.

## 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+.

```bash
# 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](.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

```bash
# 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

```json
{
  "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)

```json
{
  "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

```bash
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

```bash
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.