Apache Pinot MCP Server

Pinot MCP Server

Table of Contents

• Overview
• Features
• Quick Start
• Configuration Reference
• Docker Build
• Claude Desktop Integration
• Try a Prompt
• Security and Vulnerability Reporting
• Developer Notes
• Repo Maintainer

Overview

This project is a Python-based Model Context Protocol (MCP) server for interacting with Apache Pinot. It is built using the FastMCP framework. It is designed to integrate with Claude Desktop to enable real-time analytics and metadata queries on a Pinot cluster.

It allows you to

• List tables, segments, and schema info from Pinot
• Execute read-only SQL queries
• View index/column-level metadata
• Designed to assist business users via Claude integration
• and much more.

Features

• Every tool advertises typed input and output JSON Schemas, MCP risk annotations, and failure-recovery guidance for agent planning.
• Large query, table, segment-name, and segment-metadata responses use bounded pages with continuation metadata instead of returning unbounded agent context.
• Read-only SQL is parsed and enforced before execution; validation, permission, and transient connectivity errors are surfaced as actionable MCP errors.
• Every mutating tool supports dry_run; always preview the exact target and payload before applying. Applying requires the preview's short-lived, one-time confirmation_token, including for table-filter reloads. A preview is not a guarantee that Pinot will accept the later write.
• Single-purpose schema and table-config inspection tools avoid ambiguous combined operations: use get_schema and get_table_config independently.

MCP Tool Contract

Tool names are case-sensitive and use underscores. Version 4 renamed four tools to make every operation verb-first; clients using the former noun-first names must update their calls.

For every schema, table-config, or table-filter change, first call the same tool with dry_run=true, present the preview to the user, and call it with dry_run=false and the preview's one-time confirmation_token only after confirmation. Editing a table-filter file after preview invalidates its token. Pinot performs authoritative validation during table/schema apply calls, so a write can still fail after a successful preview.

Query execution evidence

read_query returns the existing page fields plus metadata. For example, {"query":"SELECT service, count(*) FROM events GROUP BY service","limit":20} returns metadata.completeness as complete, partial, or unknown, along with native server counts, query ID, query SHA-256, and bounded execution statistics. Missing resultTable or required execution flags remains unknown. A partial server response or group limit remains partial; an empty page is not proof of healthy telemetry. Native complete describes this bounded SQL execution, not coverage of the incident window or the entire dataset. row_limit_reached is separate from execution completeness and paging.

The MCP query path uses pinotdb>=9.2.1 through cursor.execute_native() for submission and decoding. The SDK exposes full structured query_statistics; MCP projects bounded counters and safe execution evidence into the tool response. The path submits once and does not switch transports after an ambiguous failure. Its unique clientQueryId and applicationName=mcp-pinot support optional correlation with query history or broker logs when available. Python integrations can call execute_query_with_metadata(..., timeout_seconds=5) to bound native and HTTP timeouts without modifying shared configuration. HTTP timeouts are inactivity limits; late results are rejected, but this is not native cancellation.

Tool results, including tool errors, include timing evidence in the standard MCP response _meta["io.github.startreedata/mcp-pinot"]. Existing tool data and output schemas are preserved. For example, this response metadata fragment requires no log access:

{

"_meta": { "io.github.startreedata/mcp-pinot": { "request_id": "38cb1444b20c446a96bc272531f34518", "status": "success", "admitted": true, "queue_wait_ms": 12, "execution_ms": 84, "duration_ms": 97 } } }

MCP rate-limit protocol errors preserve their JSON-RPC code and message and carry the same envelope in error.data._meta["io.github.startreedata/mcp-pinot"]. Other transport/protocol failures or cancellation may not produce a tool result.

With MCP_TRANSPORT=http on the default port 8080, a FastMCP Python client reads wire _meta through result.meta. call_tool_mcp also returns tool errors:

from fastmcp import Client

async def read_timing(): async with Client("http://localhost:8080/mcp") as client: result = await client.call_tool_mcp("read_query", {"query": "SELECT 1"}) return result.meta["io.github.startreedata/mcp-pinot"]

Orchestrators should read .meta and forward this evidence to the agent when the host does not automatically surface protocol metadata.

queue_wait_ms measures only waiting for the MCP concurrency semaphore. execution_ms measures the admitted MCP tool pipeline, including SDK HTTP work and validation; admitted=false means that pipeline never started. duration_ms covers the server's tool invocation, including admission checks, and excludes model reasoning and client delivery. status is success or error for the MCP outcome; for read_query, separately inspect metadata.completeness.

An agent can use queue_wait_ms to identify MCP admission delay, then inspect read_query's metadata.native_stats.timeUsedMs for Pinot's native query duration when present. Native query time overlaps execution_ms; their different timer boundaries do not support exact network-overhead subtraction. The shared request_id also appears in query metadata and native clientQueryId, enabling optional history/log correlation when more context is needed.

Response timing metadata contains no secrets, principal identifiers, tool arguments, SQL, or rows. Audit logs record the same timings with hashed principal identifiers. MCP_MAX_RESPONSE_BYTES limits the tool payload before this bounded timing envelope is added; it excludes the added observability metadata. Cancellation is audit-only when no response is returned and does not prove that Pinot execution stopped.

Incident tools are disabled until the server starts with --incident-profiles. See the incident evidence guide and example profile for configuration and a workflow using begin_investigation, query_incident, optional get_trace, and finish_investigation. Evidence queries expose the same response _meta timings and native request IDs when reported; log access is optional. Runs are owner-bound and budgeted; complete execution still leaves root-cause hypotheses and dataset coverage unvalidated. This first version uses bounded in-memory state in one process.

Pinot MCP in Action

See Pinot MCP in action below:

Fetching Metadata

Fetching Data, followed by analysis

Prompt: Can you do a histogram plot on the GitHub events against time

Sample Prompts

Once Claude is running, click the hammer 🛠️ icon and try these prompts:

• Can you help me analyse my data in Pinot? Use the Pinot tool and look at the list of tables to begin with.
• Can you do a histogram plot on the GitHub events against time

Quick Start

Prerequisites

Install uv (if not already installed)

uv is a fast Python package installer and resolver, written in Rust. It's designed to be a drop-in replacement for pip with significantly better performance.

curl -LsSf https://astral.sh/uv/install.sh | sh

Reload your bashrc/zshrc to take effect. Alternatively, restart your terminal

source ~/.bashrc

Installation

# Clone the repository

git clone https://github.com/startreedata/mcp-pinot.git cd mcp-pinot uv pip install -e . # Install dependencies

For development dependencies (including testing tools), use:

uv pip install -e .[dev]

Configure Pinot Cluster

The MCP server expects a uvicorn config style .env file in the root directory to configure the Pinot cluster connection. This repo includes a sample .env.example file that assumes a pinot quickstart setup.

mv .env.example .env

Configuration Reference

The server loads configuration from environment variables and from a .env file found from the current working directory. Process environment variables take precedence over .env, so deployment-time settings cannot be silently replaced by a checked-out file.

Common Profiles

Pinot Conne