Cloudera Iceberg MCP Server (via Hive)

Fork of cloudera/iceberg-mcp-server that uses Apache Hive (HiveServer2) instead of Impala for read-only access to Iceberg tables on CDP.

MCP Tools

Iceberg branching (and tagging) is supported in Hive on CDP, not Impala. See branching and tagging.

Audit / write branch workflow

1. list_iceberg_snapshots — pick a snapshot ID or timestamp

2. list_iceberg_refs — inspect existing branches/tags

3. create_iceberg_branch — fork an audit branch (FOR SYSTEM_VERSION or current head)

4. query_iceberg_branch — read branch state

5. execute_iceberg_branch_dml — write changes on the branch only

6. fast_forward_iceberg_branch — advance a branch when ready

7. drop_iceberg_branch — cleanup

Branch refs use lowercase branch_ prefix: mydb.mytable.branch_audit.

Related MCP server: MCP Trino Server

Configuration

Connection uses impyla against HiveServer2 (HTTP transport for CDP/Knox).

Example JDBC URL from CDP Data Warehouse:

jdbc:hive2://hs2-cdw-aw-se-hive.dw-se-sandbox-aws.a465-9q4k.cloudera.site/default;transportMode=http;httpPath=cliservice;ssl=true

Maps to MCP env vars:

Claude Desktop / Agent Studio

Cloudera Agent Studio (recommended)

Agent Studio only supports stdio MCP servers launched with uvx (Python) or npx (Node.js). Use a git URL so the runtime can install the package; do not use uv run unless the repo is checked out on the same machine.

{
  "mcpServers": {
    "iceberg-mcp-server-hive": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/frothkoetter/iceberg-mcp-server-hive@main",
        "run-server"
      ],
      "env": {
        "HIVE_HOST": "hs2-cdw-aw-se-hive.dw-se-sandbox-aws.a465-9q4k.cloudera.site",
        "HIVE_PORT": "443",
        "HIVE_USER": "YOUR_USER",
        "HIVE_PASSWORD": "YOUR_PASSWORD",
        "HIVE_DATABASE": "default",
        "HIVE_USE_HTTP_TRANSPORT": "true",
        "HIVE_HTTP_PATH": "cliservice",
        "HIVE_USE_SSL": "true",
        "HIVE_AUTH_MECHANISM": "LDAP"
      }
    }
  }
}

Registration tips

1. Use placeholder credentials during catalog registration; provide real HIVE_USER / HIVE_PASSWORD when attaching the MCP server to a workflow agent.

2. If you see "We could not figure out the tools offered by the MCP server", the server may still work in workflows — Agent Studio documents occasional tool-discovery failures. Add the MCP server to your agent manually and select tools there.

3. Avoid writing to stdout from wrapper scripts — stdio transport uses stdout for JSON-RPC. This server logs only through the MCP SDK.

4. Ensure the Agent Studio environment can reach HIVE_HOST on port 443 (Knox / Hive VW).

See also Cloudera MCP registration docs.

Claude Desktop (local checkout)

{
  "mcpServers": {
    "iceberg-mcp-server-hive": {
      "command": "uv",
      "args": ["run", "run-server"],
      "env": {
        "HIVE_HOST": "hs2-your-cluster.example.cloudera.site",
        "HIVE_PORT": "443",
        "HIVE_USER": "username",
        "HIVE_PASSWORD": "password",
        "HIVE_DATABASE": "default"
      }
    }
  }
}

Local development

git clone https://github.com/<your-org>/iceberg-mcp-server-hive.git
cd iceberg-mcp-server-hive
uv sync --dev
export HIVE_HOST=... HIVE_USER=... HIVE_PASSWORD=...
uv run run-server

Differences from upstream (Impala)

• Environment variables use HIVE_* instead of IMPALA_*

• get_schema returns {database, tables} and accepts an optional database name

• Added list_databases tool

• execute_query returns {columns, rows} for SELECT results

Examples

See ./examples for LangChain and OpenAI SDK notebooks (update env vars from IMPALA_* to HIVE_*).

Copyright (c) 2025 - Cloudera, Inc. All rights reserved.