MCP Pinot Server - Model Context Protocol for Apache Pinot

Why MCP Pinot?

Bridge the gap between conversational AI and real-time OLAP analytics with a secure, production-ready server.

🔍

14 MCP Tools

Query data, list tables, inspect schemas, and preview configuration changes through any compatible MCP client.

🔒

Security First

Read-only SQL queries, table-level filtering with glob patterns, OAuth authentication, and TLS/SSL support.

🌐

Flexible Transport

STDIO for desktop integration and Streamable HTTP for local or authenticated remote MCP clients.

☸

Kubernetes Ready

A configurable Helm chart with health checks, optional network policy, disruption budgets, and ingress support.

⚡

Standard MCP

Typed MCP tools, prompts, and resources over standard transports — no proprietary REST tool API required.

🧪

Battle Tested

Comprehensive unit and integration coverage, typed contracts, structured logging, and actionable errors.

Available Tools

14 typed MCP tools with case-sensitive, underscore-separated identifiers.

Tool	Description	Category
`test_connection`	Test and diagnose Pinot cluster connectivity	Query
`read_query`	Execute read-only SELECT queries on Pinot tables	Query
`list_tables`	Page through table names visible to this server	Metadata
`get_table_size`	Get table size and storage information	Metadata
`list_segments`	Page through exact segment names for a table	Metadata
`list_segment_metadata`	Page through detailed metadata for table segments	Metadata
`get_segment_index_metadata`	Inspect index and column-level information	Metadata
`get_schema`	Fetch a schema by name	Config
`create_schema`	Preview or create a Pinot schema	Config
`update_schema`	Preview or update an existing schema	Config
`get_table_config`	Retrieve table configuration	Config
`create_table_config`	Preview or create a table configuration	Config
`update_table_config`	Preview or update a table configuration	Config
`reload_table_filters`	Preview by default, then apply the unchanged candidate with its confirmation token	Config

Schema, table-config, and table-filter tools can change live state. Call the intended tool with dry_run=true, show the exact preview to the user, and apply with dry_run=false plus the preview's one-time confirmation_token only after confirmation. A preview is non-mutating but does not guarantee that Pinot will accept the later write. Editing a table-filter file after preview invalidates its token.

Quick Start

Get up and running in under 5 minutes.

Install uv

A fast Python package installer written in Rust.

Terminal

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

Clone & Install

Clone the repository and install dependencies.

Terminal

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

Configure

Set up your Pinot cluster connection.

Terminal

# Copy the example config
mv .env.example .env

# Edit with your Pinot cluster details
# PINOT_CONTROLLER_URL=http://localhost:9000
# PINOT_BROKER_URL=http://localhost:8000

Run the Server

Start the MCP server with the configured transport.

Terminal

uv --directory . run mcp_pinot/server.py

Optional: Launch Pinot QuickStart

If you don't have a Pinot cluster, start the QuickStart with Docker:

Terminal

docker run --name pinot-quickstart \
  -p 2123:2123 -p 9000:9000 -p 8000:8000 \
  -d apachepinot/pinot:1.5.1 QuickStart -type batch

Integration

Connect a desktop host, use Streamable HTTP, or deploy on Kubernetes.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pinot_mcp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/mcp-pinot",
        "run",
        "mcp_pinot/server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PINOT_CONTROLLER_URL": "http://localhost:9000",
        "PINOT_BROKER_URL": "http://localhost:8000"
      }
    }
  }
}

Replace paths with your actual uv and repo locations. Run which uv to find the uv path. Use STDIO transport for Claude Desktop.

Terminal — MCP client

# Start the local Streamable HTTP server at /mcp
MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=8080 uv run mcp-pinot

# In another terminal, connect with the bundled MCP client
uv run python examples/example_client.py

Use an MCP SDK or compatible host for initialization and tool calls. The server does not expose custom /api/tools/* REST endpoints.

Terminal

# Build the image
docker build -t mcp-pinot .

# Run with your config
docker run -v $(pwd)/.env:/app/.env mcp-pinot

Terminal — Helm

# Deploy with Helm
helm install mcp-pinot ./helm/mcp-pinot \
  --set pinot.controller.url=http://pinot-controller:9000 \
  --set pinot.broker.url=http://pinot-broker:8000

# Expose through a Service only with OAuth enabled
helm upgrade mcp-pinot ./helm/mcp-pinot \
  --set service.enabled=true \
  --set mcp.host=0.0.0.0 \
  --set mcp.oauth.enabled=true

See It in Action

MCP Pinot Server working with Claude AI for real-time data analysis.

MCP Pinot fetching metadata from a Pinot cluster

Metadata Exploration

Ask Claude to explore your Pinot cluster — list tables, inspect schemas, and understand your data model.

MCP Pinot analyzing GitHub events data with histogram

Data Analysis & Visualization

Query data and generate visualizations like histograms, all through natural language prompts.

Configuration

Configure Pinot connectivity, MCP transport, authentication, and deployment exposure.

The server loads environment variables and a .env file from the current working directory. Process environment variables take precedence over .env. STDIO is the safe default; select HTTP explicitly and enable an auth provider before binding to a non-loopback host.

Claude Desktop

Use STDIO for local desktop integrations.

MCP_TRANSPORT=stdio

Local HTTP

Explicit Streamable HTTP profile for local development.

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1

Remote HTTP

Network exposure requires OAuth or static-token auth, plus TLS or an authenticated proxy.

MCP_HOST=0.0.0.0
AUTH_PROVIDER=oauth

Helm Exposure

Services are opt-in and must be OAuth-gated for non-loopback hosts.

service.enabled=true

Pinot Connection

Use either PINOT_BROKER_URL or the individual broker host, port, and scheme overrides.

Variable	Description	Default / Notes
`PINOT_CONTROLLER_URL`	Pinot controller endpoint	`http://localhost:9000`
`PINOT_BROKER_URL`	Pinot broker endpoint	`http://localhost:8000`
`PINOT_BROKER_HOST`	Optional broker host override	Parsed from `PINOT_BROKER_URL`
`PINOT_BROKER_PORT`	Optional broker port override	Parsed from `PINOT_BROKER_URL`
`PINOT_BROKER_SCHEME`	Optional broker scheme override	Parsed from `PINOT_BROKER_URL`
`PINOT_USERNAME` / `PINOT_PASSWORD`	Basic authentication for Pinot	—
`PINOT_TOKEN`	Bearer or raw token for Pinot	Takes precedence over token file
`PINOT_TOKEN_FILENAME`	File containing a Pinot token	—
`PINOT_DATABASE`	Optional database header	empty
`PINOT_USE_MSQE`	Enable Pinot multi-stage query engine	`false`
`PINOT_REQUEST_TIMEOUT`	HTTP request timeout in seconds	`60`
`PINOT_CONNECTION_TIMEOUT`	HTTP connection timeout in seconds	`60`
`PINOT_QUERY_TIMEOUT`	SQL query timeout in seconds	`60`

MCP Server

STDIO is the default. Explicit HTTP binds to loopback; non-loopback binds fail closed unless OAuth or static-token authentication is enabled. Run one process or Helm replica while confirmation and rate-limit state are process-local.

Variable	Description	Default / Notes
`MCP_TRANSPORT`	Transport mode: `stdio` or `http`	`stdio`
`MCP_HOST`	HTTP bind address	`127.0.0.1`
`MCP_PORT`	HTTP port	`8080`
`MCP_PATH`	MCP HTTP path	`/mcp`
`MCP_SSL_CERTFILE`	Path to SSL certificate for HTTPS	—
`MCP_SSL_KEYFILE`	Path to SSL private key	—
`MCP_LOG_LEVEL`	Application logging level written to stderr	`INFO`
`MCP_RATE_LIMIT_RPS` / `MCP_RATE_LIMIT_BURST`	Per-principal or loopback-peer tool-call limits	`10` / `20`
`MCP_CONFIRMATION_TTL_SECONDS`	Lifetime of process-bound one-time confirmation tokens	`300`

OAuth and Access Controls

OAuth or static-token authentication is required for HTTP or HTTPS exposure outside loopback. Component scopes enforce read/write/admin access. Table filtering improves UX, but Pinot ACLs remain the production security boundary.

Variable	Description	Default / Notes
`AUTH_PROVIDER`	Inbound authentication provider: `oauth` or `static`	Required for non-loopback HTTP
`MCP_STATIC_TOKEN`	Shared bearer secret for a service principal	Required for the static provider
`MCP_STATIC_SCOPES`	Space- or comma-separated Pinot component scopes	`pinot:read pinot:write pinot:admin`
`PINOT_TABLE_FILTER_FILE`	YAML file for table filtering	Startup fails if configured and missing
`OAUTH_ENABLED`	Enable OAuth authentication	`false`
`OAUTH_CLIENT_ID`	OAuth client ID	Required when OAuth is enabled
`OAUTH_CLIENT_SECRET`	OAuth client secret	Required when OAuth is enabled
`OAUTH_BASE_URL`	Public base URL for this MCP server	`http://localhost:8080`
`OAUTH_AUTHORIZATION_ENDPOINT`	Upstream authorization endpoint	Required when OAuth is enabled
`OAUTH_TOKEN_ENDPOINT`	Upstream token endpoint	Required when OAuth is enabled
`OAUTH_JWKS_URI`	JWKS URI used for token verification	Required when OAuth is enabled
`OAUTH_ISSUER`	Expected token issuer	Required when OAuth is enabled
`OAUTH_AUDIENCE`	Canonical MCP resource URI expected in the token audience	Required when OAuth is enabled
`OAUTH_EXTRA_AUTH_PARAMS`	Additional authorization parameters as JSON	—

See the README configuration reference, SECURITY.md, and Helm chart docs for deployment details.

Real-Time Analytics with Apache Pinot + Claude AI

Why MCP Pinot?

14 MCP Tools

Security First

Flexible Transport

Kubernetes Ready

Standard MCP

Battle Tested

Available Tools

Quick Start

Install uv

Clone & Install

Configure

Run the Server

Optional: Launch Pinot QuickStart

Integration

See It in Action

Configuration

Claude Desktop

Local HTTP

Remote HTTP

Helm Exposure

Pinot Connection

MCP Server

OAuth and Access Controls

Real-Time Analytics
with Apache Pinot + Claude AI