Production-Ready MCP Server

Real-Time Analytics
with Apache Pinot + Claude AI

A production-grade Model Context Protocol server that connects Claude AI to your Apache Pinot cluster for real-time analytics, metadata queries, and schema management.

Get Started View on GitHub
$ pip install mcp-pinot-server

Why MCP Pinot?

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

🔍

15 MCP Tools

Query data, list tables, inspect schemas, manage configurations, and more — all through natural language via Claude.

🔒

Security First

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

🌐

Flexible Transport

STDIO for Claude Desktop integration and HTTP/SSE for web applications with secure local defaults.

☸

Kubernetes Ready

Complete Helm charts and K8s manifests with health checks, autoscaling, and Ingress TLS termination.

⚡

REST API

Direct HTTP endpoints for tool calls — integrate with any language or framework using simple JSON requests.

🧪

Battle Tested

45+ tests with comprehensive coverage, async support, structured logging, and graceful error handling.

Available Tools

15 MCP tools for querying data, managing schemas, and controlling table configurations.

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 List all available tables in the cluster Metadata
table-details Get table size and storage information Metadata
segment-list List all segments for a given table Metadata
segment-metadata-details Get detailed metadata for table segments Metadata
index-column-details Inspect index and column-level information Metadata
tableconfig-schema-details Get combined table config and schema Config
get-schema Fetch a schema by name Config
create-schema Create new schemas with override/force options Config
update-schema Modify existing schemas Config
get-table-config Retrieve table configuration Config
create-table-config Create new table configurations Config
update-table-config Modify existing table configurations Config
reload-table-filters Dynamically reload table access filters without restarting Config

Quick Start

Get up and running in under 5 minutes.

1

Install uv

A fast Python package installer written in Rust.

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

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 .
3

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
4

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:latest QuickStart -type batch

Integration

Connect to Claude Desktop, use HTTP APIs, 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 — curl
# List available tools
curl -s http://127.0.0.1:8080/api/tools/list | jq

# Execute a query
curl -X POST http://127.0.0.1:8080/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "read-query", "arguments": {"query": "SELECT * FROM airlineStats LIMIT 5"}}'

# List tables
curl -X POST http://127.0.0.1:8080/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "list-tables", "arguments": {}}'
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. Values in .env override process environment variables. Keep local defaults for desktop use, and enable OAuth before binding HTTP or HTTPS to a non-loopback host.

Claude Desktop

Use STDIO for local desktop integrations.

MCP_TRANSPORT=stdio

Local HTTP

Default HTTP/SSE profile for local development.

MCP_HOST=127.0.0.1

Remote HTTP

Network exposure requires OAuth and TLS or an authenticated proxy.

MCP_HOST=0.0.0.0
OAUTH_ENABLED=true

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

HTTP binds to loopback by default. Non-loopback binds fail closed unless OAuth is enabled.

Variable Description Default / Notes
MCP_TRANSPORT Transport mode: stdio or http http
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 —

OAuth and Access Controls

OAuth is required for HTTP or HTTPS exposure outside loopback. Table filtering improves UX, but Pinot ACLs remain the production security boundary.

Variable Description Default / Notes
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 Optional expected audience claim —
OAUTH_EXTRA_AUTH_PARAMS Additional authorization parameters as JSON —

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