Iceberg MCP Server

What is Iceberg MCP Server about?

Iceberg MCP Server is a Model Context Protocol (MCP) service that connects to an Apache Impala coordinator and allows language models to inspect Iceberg table schemas and run read‑only SQL queries. The server returns results in JSON, making it easy for AI applications to consume database information without granting write access.

How to use Iceberg MCP Server?

Configure environment variables for Impala connection:
- IMPALA_HOST
- IMPALA_PORT
- IMPALA_USER
- IMPALA_PASSWORD
- IMPALA_DATABASE
Choose a transport (default is stdio). Set MCP_TRANSPORT to stdio, http, or sse as needed.

Run the server using one of the provided commands:

Direct from GitHub with uvx:

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/cloudera/iceberg-mcp-server@main", "run-server"]
}

Locally after cloning with uv:

{
  "command": "uv",
  "args": ["--directory", "/path/to/iceberg-mcp-server", "run", "src/iceberg_mcp_server/server.py"]
}

Integrate with Claude Desktop, LangChain, LangGraph, OpenAI SDK, or any client that can speak MCP.

Key features

Schema discovery via get_schema() – lists all tables in the selected Impala database.
Read‑only query execution via execute_query(query) – runs any SELECT‑type SQL and returns JSON results.
Multiple transport options – stdio (default), http, and sse for flexible deployment.
Zero‑write safety – designed strictly for inspection and read‑only analytics.
Ready‑to‑use examples for popular AI frameworks.

Use cases

Enabling LLMs to understand and navigate large Iceberg data lakes without exposing mutable operations.
Building conversational data‑analytics assistants that can answer questions about table structures and query results.
Integrating Iceberg metadata into AI‑powered data catalogues or lineage tools.
Rapid prototyping of AI agents that need to fetch business intelligence from Impala.

FAQ

Q: Can I run write queries? A: No. The server only supports read‑only SELECT statements to protect data integrity.

Q: Which transport should I choose? A: Use stdio for local CLI tools or Claude Desktop. Choose http for network‑exposed services, and sse for event‑driven web deployments.

Q: Do I need a Python environment? A: Yes. The server is Python‑based; uv/uvx handle dependency isolation and execution.

Q: How do I secure credentials? A: Store Impala credentials in environment variables or a secret manager and avoid committing them to source control.

Q: Is there support for other databases? A: This server is specific to Iceberg tables accessed through Impala. Separate MCP servers would be needed for other data sources.

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.

Iceberg MCP Server