# Apache Hive MCP Server

An [MCP](https://modelcontextprotocol.io/) server for Apache Hive (HiveServer2),
built with [FastMCP](https://github.com/jlowin/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](https://github.com/cloudera/iceberg-mcp-server):
  same `execute_query` + `get_schema` tools and structure, with the connection
  layer swapped to HiveServer2 via [`impyla`](https://github.com/cloudera/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](https://github.com/jlowin/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)

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

### CDP Public Cloud (CDW Virtual Warehouse)

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

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

```bash
# 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](#configuration) and the presets above).

```json
{
    "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](#deployment-presets).
`@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/`](./examples/agent-studio/).

---

## Smoke test

1. Start a local HiveServer2 (e.g., Apache Hive Docker image):
   ```bash
   docker run -d -p 10000:10000 apache/hive:3.1.3
   ```
2. Configure `.env` with the local preset above.
3. Start the server:
   ```bash
   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](LICENSE).