iceberg-mcp-server-hive
This server provides read-only and branch-based access to Apache Iceberg tables via HiveServer2, enabling SQL querying, schema exploration, and Iceberg branch/snapshot management.
Execute read-only queries: Run
SELECT,SHOW,DESCRIBE,WITH, andEXPLAINSQL statements on Hive/Iceberg tables.List tables: Retrieve table names from the configured or a specified Hive database.
List databases: Enumerate all Hive databases visible to the connected user.
List Iceberg snapshots: View snapshot history for a table.
List Iceberg refs: Inspect existing branches and tags on a table.
Create Iceberg branches: Fork a branch from the current state, a specific snapshot ID, or a timestamp.
Drop Iceberg branches: Remove an existing branch.
Fast-forward Iceberg branches: Advance a branch along its hierarchy.
Query Iceberg branches: Read data from a specific branch.
Execute DML on branches: Perform
INSERT,UPDATE, orDELETEoperations on a branch.
Provides read-only access to Iceberg tables on Cloudera Data Platform (CDP) via Apache Hive (HiveServer2).
Allows querying Iceberg tables on Cloudera Data Platform (CDP) using Hive.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@iceberg-mcp-server-hive list all databases"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Tool | Description |
| Run read-only SQL ( |
| List tables in the configured or given database |
| List all visible Hive databases |
| Snapshot history ( |
| Branches and tags ( |
| Create branch from current state, snapshot ID, or timestamp |
| Drop a branch |
| Fast-forward branch hierarchy |
| Read from |
|
|
Iceberg branching (and tagging) is supported in Hive on CDP, not Impala. See branching and tagging.
Audit / write branch workflow
list_iceberg_snapshots— pick a snapshot ID or timestamplist_iceberg_refs— inspect existing branches/tagscreate_iceberg_branch— fork an audit branch (FOR SYSTEM_VERSIONor current head)query_iceberg_branch— read branch stateexecute_iceberg_branch_dml— write changes on the branch onlyfast_forward_iceberg_branch— advance a branch when readydrop_iceberg_branch— cleanup
Branch refs use lowercase branch_ prefix: mydb.mytable.branch_audit.
Related MCP server: Cloudera Iceberg MCP 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=trueMaps to MCP env vars:
JDBC / CDP | Env var |
Host in URL |
|
Path after host ( |
|
|
|
|
|
|
|
Port (443 implied) |
|
LDAP user/password |
|
Variable | Default | Description |
| — | HiveServer2 or Knox gateway host |
|
| HS2 port (443 for Knox HTTP) |
| — | LDAP / service user |
| — | Password |
|
| Default database for |
|
| impyla auth mechanism |
|
| HTTP transport (typical on CDP) |
|
| Knox / HS2 HTTP path |
|
| TLS |
|
|
|
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
Use placeholder credentials during catalog registration; provide real
HIVE_USER/HIVE_PASSWORDwhen attaching the MCP server to a workflow agent.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.
Avoid writing to stdout from wrapper scripts — stdio transport uses stdout for JSON-RPC. This server logs only through the MCP SDK.
Ensure the Agent Studio environment can reach
HIVE_HOSTon port 443 (Knox / Hive VW).
See also Cloudera MCP registration docs.
Troubleshooting MCP server load failures
If CrewAI Agent Studio, Cursor, or another MCP host fails to connect to this server via uvx,
check the following.
FastMCP / mcp import error
uvx installs the latest mcp package (currently 2.x). MCP Python SDK 2.0 renamed FastMCP to
MCPServer. Older server builds crash on startup with:
ImportError: cannot import name 'FastMCP' from 'mcp.server'Use a server build that includes the dual-import fix (MCPServer + FastMCP fallback), or pin
mcp>=1.28,<2 in your environment.
Verify locally:
HIVE_HOST="hs2.example.cloudera.site" \
HIVE_USER="test" HIVE_PASSWORD="test" \
uv run python scripts/test_mcp_stdio.py uvx --from . run-serverExpected output: OK initialize and OK tools/list: 10 tools.
Ensure uvx is on the Agent Studio host PATH (which uvx).
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-serverDifferences from upstream (Impala)
Environment variables use
HIVE_*instead ofIMPALA_*get_schemareturns{database, tables}and accepts an optional database nameAdded
list_databasestoolexecute_queryreturns{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.
Available Tools
3 toolsexecute_queryA
Execute a read-only SQL query on Hive (Iceberg tables) and return JSON results.
Inputs: query (required).
get_schemaA
List table names in the configured Hive database, or in an optional database.
Inputs: database.
list_databasesA
List all Hive databases visible to the connected user.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct function: executing queries, listing tables, and listing databases. There is no overlap in purpose.
All tool names follow a consistent verb_noun pattern using snake_case, making them predictable and easy to understand.
With only three tools, the server is minimal but covers the essential read-only operations for Hive databases. The count is reasonable given the focused scope.
The server lacks a tool for retrieving detailed table schema or previewing data, which are common needs when exploring databases. This is a notable gap for a read-only explorer.
Related MCP Connectors
Read your Iceberg tables hosted in Europe: find tables, run read-only SQL, view photos.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Governed SQL access to your databases: redaction, query review and an audit log.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Related MCP Servers
- FlicenseBqualityDmaintenanceA Model Context Protocol server that provides a SQL interface for querying and managing Apache Iceberg tables through Claude desktop, allowing natural language interaction with Iceberg data lakes.18-
- AlicenseBqualityDmaintenanceEnables 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.213Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Iceberg tables via Apache Impala, enabling LLMs to inspect database schemas and execute SQL queries on Iceberg data.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP Server for Apache Iceberg, enabling users to read, query, and manipulate data within Iceberg catalogs.230 PyPI2Apache 2.0