Cloudera Iceberg MCP Server for Read-Only Impala Access

Overview

The Cloudera Iceberg MCP Server exposes read-only access to Iceberg tables through Apache Impala using the Model Context Protocol (MCP). It is intended for developer workflows that let LLMs or other AI agents inspect table schemas and run SELECT-style queries safely against a production or staging data lake without granting write access.

This server translates MCP requests into Impala queries and returns results as JSON, making the data easily consumable by LLMs, notebook tools, or orchestration frameworks. The server supports multiple transport modes (stdio, HTTP, SSE) so it can run locally, inside desktop assistants, or as a networked microservice.

Features

• Read-only access to Iceberg tables via Impala (SELECT queries only).
• Two primary RPC tools available to clients:
  • execute_query(query: str): run a SQL query and return JSON results.
  • get_schema(): list tables and basic schema information for the configured database.
• Configurable transports: stdio (default), http, sse.
• Simple environment-variable configuration for Impala connection and server behavior.
• Example integrations for common AI frameworks included (LangChain, OpenAI SDK, etc.).
• Minimal runtime dependency surface—designed to be embedded into developer tooling like Claude Desktop.

Installation / Configuration

There are two common ways to install and run the MCP server: install directly from the GitHub repository at runtime, or run from a cloned local checkout.

Recommended: run from GitHub using a tool that can install from VCS (example uses uvx):

{
  "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"
      }
    }
  }
}

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"
      }
    }
  }
}

Environment variables

Notes:

• The server enforces read-only access. Only SELECT and schema-inspection queries are intended; avoid running DDL/DML with production credentials.
• For production deployments use a read-only Impala account and secure transport (TLS/LDAP) as required by your environment.

Available Resources

• execute_query(query: str) -> JSON: Execute a SQL SELECT query against the configured Impala database and return rows as JSON objects.
• get_schema() -> JSON: Return a list of tables in the configured database and basic column metadata for each table.
• Examples folder: The repository contains example integrations for LangChain, LangGraph, and direct OpenAI SDK usage to show how to call the MCP server from popular AI frameworks.

Transport modes:

• stdio (default) — best for local CLI tools, desktop MCP clients (e.g., Claude Desktop).
• http — exposes an HTTP endpoint for web or microservice-based deployments.
• sse — server-sent events transport for streaming updates to web clients.

Use Cases

• LLM schema inspection: Allow a large language model to discover available tables and column types before composing data-oriented prompts (e.g., “Which table holds user events?”).
• Safe ad-hoc analytics: Let analysts or agents run read-only SELECT queries and receive structured JSON results for downstream processing or visualization.
• Data catalog augmentation: Use get_schema() to populate or validate an automated data catalog with Iceberg schema metadata.
• QA and data validation: Run read-only queries from CI jobs or data pipelines to validate schema changes or sample data quality without granting write privileges.
• Embedding generation for semantic search: Pull sample rows as JSON, then pass those to an embedding pipeline to create searchable vector indices.

Example: Basic execute_query call

Clients using MCP will call execute_query with a string SQL statement and receive JSON rows. Internally the server runs the query via Impala and maps rows/columns into a JSON array suitable for LLM consumption and downstream tools.

Security and best practices

• Use a dedicated read-only Impala user for MCP access.
• Ensure Impala endpoints are accessed over TLS where available; use network controls to limit who can connect.
• Sanitize and monitor queries run through the MCP server; consider query limits and timeout settings in production.
• Avoid embedding long-lived plaintext secrets in client repositories; prefer environment secrets or secret managers.

For developer examples and integration patterns, see the repository’s examples/ directory which includes sample clients for common AI frameworks.