Apache Hive MCP Server

An MCP server for Apache Hive (HiveServer2), built with FastMCP. Connects to any HiveServer2-compatible endpoint — open-source Apache Hive, Cloudera CDP Base, or Cloudera CDP Public Cloud (CDW) — and exposes two read-only tools that an LLM agent can call.

---

Project summary

• What it is — a Model Context Protocol server that lets an LLM agent query Apache Hive: list tables and run read-only SQL, with results returned as JSON.
• Feature parity — mirrors Cloudera's Impala/Iceberg MCP server: same execute_query + get_schema tools and structure, with the connection layer swapped to HiveServer2 via impyla.
• Works everywhere HiveServer2 does — open-source Apache Hive, CDP Base (Kerberos/LDAP), and CDP Public Cloud / CDW (Knox, LDAP over HTTPS). Auth, transport, and TLS are all driven by HIVE_* environment variables.
• Safe by default — execute_query enforces a read-only prefix guard (SELECT/SHOW/DESCRIBE/WITH); write/DDL statements are rejected before a connection is opened.
• Transport — stdio (default), http, or sse, selected via MCP_TRANSPORT.
• Tech stack — Python ≥3.10, FastMCP, impyla, uv. 11 unit tests (connection mocked — no live Hive required).

---

Tools

Tool	Signature	Description
execute_query	execute_query(query: str) -> str	Execute a read-only SQL query (SELECT, SHOW, DESCRIBE, WITH) and return results as a JSON array of column-keyed objects. Write operations are rejected with an error string.
get_schema	get_schema() -> str	Run SHOW TABLES against the configured database and return the table list as a JSON array of strings.

---

Configuration

All configuration is via environment variables (or a .env file at the project root).

Variable	Default	Description
HIVE_HOST	localhost	HiveServer2 hostname or IP
HIVE_PORT	10000	HiveServer2 thrift port
HIVE_DATABASE	default	Database to connect to
HIVE_USER	(empty)	Username (leave empty for NOSASL/Kerberos)
HIVE_PASSWORD	(empty)	Password (used with PLAIN/LDAP)
HIVE_AUTH_MECHANISM	PLAIN	Auth method: NOSASL, PLAIN, LDAP, GSSAPI
HIVE_USE_HTTP_TRANSPORT	false	Use HTTP transport instead of binary thrift
HIVE_HTTP_PATH	cliservice	HTTP path when HIVE_USE_HTTP_TRANSPORT=true
HIVE_USE_SSL	false	Enable TLS for the thrift connection
HIVE_KERBEROS_SERVICE_NAME	hive	Kerberos service principal name (GSSAPI only)
MCP_TRANSPORT	stdio	MCP transport: stdio, http, or sse

Copy .env.example to .env and fill in your values.

---

Deployment presets

Local / development (Docker HiveServer2)

HIVE_HOST=localhost
HIVE_PORT=10000
HIVE_DATABASE=default
HIVE_AUTH_MECHANISM=NOSASL
MCP_TRANSPORT=stdio

CDP Public Cloud (CDW Virtual Warehouse)

HIVE_HOST=<coordinator-hostname>.dw.cloudera.site
HIVE_PORT=443
HIVE_DATABASE=default
HIVE_USER=<workload-username>
HIVE_PASSWORD=<workload-password>
HIVE_AUTH_MECHANISM=LDAP
HIVE_USE_HTTP_TRANSPORT=true
HIVE_HTTP_PATH=cliservice
HIVE_USE_SSL=true
MCP_TRANSPORT=stdio

CDP Base / on-premises with Kerberos

HIVE_HOST=<hiveserver2-host.example.com>
HIVE_PORT=10000
HIVE_DATABASE=default
HIVE_AUTH_MECHANISM=GSSAPI
HIVE_KERBEROS_SERVICE_NAME=hive
MCP_TRANSPORT=stdio

Obtain a Kerberos ticket (kinit) before starting the server.

---

Running

# Install
pip install -e .
# or with uv:
uv sync

# Copy and edit config
cp .env.example .env

# Start (stdio transport, for use with an MCP host)
uv run hive-mcp-server

---

MCP client configuration

MCP hosts (Claude Desktop, Cloudera AI Agent Studio, etc.) register servers with a mcpServers JSON block. uvx runs this server straight from GitHub — no local install or PyPI publish required. Fill in the HIVE_* values for your environment (see Configuration and the presets above).

{
    "mcpServers": {
        "Hive": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/avelloal/hive-mcp-server@v0.1.0",
                "hive-mcp-server"
            ],
            "env": {
                "HIVE_HOST": "<coordinator-hostname>.dw.cloudera.site",
                "HIVE_PORT": "443",
                "HIVE_DATABASE": "default",
                "HIVE_USER": "<workload-username>",
                "HIVE_PASSWORD": "<workload-password>",
                "HIVE_AUTH_MECHANISM": "LDAP",
                "HIVE_USE_HTTP_TRANSPORT": "true",
                "HIVE_HTTP_PATH": "cliservice",
                "HIVE_USE_SSL": "true"
            }
        }
    }
}

The example above targets CDP Public Cloud / CDW. For local or Kerberos targets, swap the env values using the presets above. @v0.1.0 pins a fixed release — drop it to track the latest, or bump it for a newer version.

For Cloudera AI Agent Studio specifically (registration steps, env-var handling, stdio/uvx limitations), see examples/agent-studio/.

---

Smoke test

1. Start a local HiveServer2 (e.g., Apache Hive Docker image):

   docker run -d -p 10000:10000 apache/hive:3.1.3
   

2. Configure .env with the local preset above.
3. Start the server:

   uv run hive-mcp-server
   

4. In a second terminal, use the fastmcp dev inspector or any MCP client to call both tools:
   • get_schema() — should return [] or a list of table names.
   • execute_query("SHOW DATABASES") — should return a JSON array of databases.

---

License

Apache License 2.0 — see LICENSE.