Cloudera Iceberg MCP Server

What is Cloudera Iceberg MCP Server about?

Enables LLMs and other AI agents to inspect Iceberg table schemas and run read‑only SQL queries through Impala, returning results in JSON format.

How to use Cloudera Iceberg MCP Server?

Add a configuration block to the mcpServers section of claude_desktop_config.json. Two installation methods are supported:

1. Direct installation from GitHub – use uvx to fetch and run the server in one step.
2. Local installation – clone the repository and invoke the server script with uv. Set the required IMPALA_* environment variables (host, port, user, password, database) to match your Impala deployment. The transport defaults to stdio but can be switched to http or sse via MCP_TRANSPORT.

Key Features

• execute_query(query: str): runs any SQL query against Impala and returns JSON results.
• get_schema(): lists all tables in the configured Impala database.
• Configurable transport (stdio, http, sse).
• Ready‑made examples for LangChain, LangGraph, and OpenAI SDK integrations.
• No write permissions – safe for read‑only inspection.

Use Cases

• Allow LLMs to understand the structure of data lakes built on Iceberg.
• Enable AI agents to answer data‑driven questions without direct database credentials.
• Integrate with LangChain agents that need to fetch tabular data for reasoning.
• Provide a lightweight bridge for web services that require schema discovery and query execution over Impala.

FAQ

Q: Do I need a full Impala client installed? A: No. The server connects to Impala using the provided host, port, and credentials; only the Python runtime and uv/uvx are required.

Q: Can I run the server over HTTP? A: Yes. Set MCP_TRANSPORT=http to expose an HTTP endpoint.

Q: Is write access possible? A: The server is intentionally read‑only; any write‑oriented SQL will be rejected.

Q: Which Python versions are supported? A: The project follows standard Python 3.x compatibility; using uvx ensures the appropriate environment.

Q: How do I change the default database? A: Adjust the IMPALA_DATABASE environment variable in the configuration.

Cloudera Iceberg MCP Server (via Impala)

This is a A Model Context Protocol server that provides read-only access to Iceberg tables via Apache Impala. This server enables LLMs to inspect database schemas and execute read-only queries.

• execute_query(query: str): Run any SQL query on Impala and return the results as JSON.
• get_schema(): List all tables available in the current database.

Usage with Claude Desktop

To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your claude_desktop_config.json:

Option 1: Direct installation from GitHub (Recommended)

{
  "mcpServers": {
    "iceberg-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/cloudera/iceberg-mcp-server@main",
        "run-server"
      ],
      "env": {
        "IMPALA_HOST": "coordinator-default-impala.example.com",
        "IMPALA_PORT": "443",
        "IMPALA_USER": "username",
        "IMPALA_PASSWORD": "password",
        "IMPALA_DATABASE": "default"
      }
    }
  }
}

Option 2: Local installation (after cloning the repository)

{
  "mcpServers": {
    "iceberg-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/iceberg-mcp-server",
        "run",
        "src/iceberg_mcp_server/server.py"
      ],
      "env": {
        "IMPALA_HOST": "coordinator-default-impala.example.com",
        "IMPALA_PORT": "443",
        "IMPALA_USER": "username",
        "IMPALA_PASSWORD": "password",
        "IMPALA_DATABASE": "default"
      }
    }
  }
}

For Option 2, replace /path/to with your path to this repository. Set the environment variables according to your Impala configuration.

Usage with AI frameworks

The ./examples folder contains several examples how to integrate this MCP Server with common AI Frameworks like LangChain/LangGraph, OpenAI SDK.

Transport

The MCP server's transport protocol is configurable via the MCP_TRANSPORT environment variable. Supported values:

• stdio (default) — communicate over standard input/output. Useful for local tools, command-line scripts, and integrations with clients like Claude Desktop.
• http - expose an HTTP server. Useful for web-based deployments, microservices, exposing MCP over a network.
• sse — use Server-Sent Events (SSE) transport. Useful for existing web-based deployments that rely on SSE.

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