Pinot

You run a Pinot MCP Server to interact with an Apache Pinot cluster using the MCP protocol. This enables you to list tables and metadata, run read-only SQL queries, and inspect index and column information through a lightweight, real-time interface that integrates with Claude Desktop for analytics and prompt-driven analysis.

How to use

You use an MCP client to connect to the Pinot MCP Server exposed locally or remotely. Start the server, then use your MCP client to list tables, fetch metadata, execute read-only queries, and view schema details from Pinot. The server is designed to work with Claude Desktop for real-time analytics and metadata queries on your Pinot cluster.

How to install

Prerequisites: Python environment with uvx install tooling and access to the Pinot cluster. You will install the MCP server in editable mode to develop against it.

Install the uv tool if it is not already installed. Run the following script to install uv and refresh your shell:

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

# Reload your shell configuration or restart the terminal
# source ~/.bashrc

Clone the MCP Pinot repository and install dependencies in editable mode. Run these commands in sequence:

git clone https://github.com/startreedata/mcp-pinot.git
cd mcp-pinot
uv pip install -e .
# For development dependencies (optional):
# uv pip install -e .[dev]

Configure Pinot connection by creating a configuration file in the root directory. Use the provided sample and adapt to your Pinot quickstart setup. Then prepare to run the server.

mv .env.example .env

Optionally enable table filtering to restrict which Pinot tables are visible. Copy the example filter and tailor it to your environment, then reference it from the environment configuration.

cp table_filters.yaml.example table_filters.yaml

Then specify the filter file path in your environment:

PINOT_TABLE_FILTER_FILE=table_filters.yaml

Additional configuration notes

Configure OAuth if you want to secure access to the MCP server. Set the following environment variables when enabling OAuth: OAUTH_ENABLED, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_BASE_URL, OAUTH_AUTHORIZATION_ENDPOINT, OAUTH_TOKEN_ENDPOINT, OAUTH_JWKS_URI, OAUTH_ISSUER, and optionally OAUTH_AUDIENCE and OAUTH_EXTRA_AUTH_PARAMS.

OAUTH_ENABLED=true
OAUTH_CLIENT_ID=client-id
OAUTH_CLIENT_SECRET=client-secret
OAUTH_BASE_URL=http://localhost:8000
OAUTH_AUTHORIZATION_ENDPOINT=https://example.com/oauth/authorize
OAUTH_TOKEN_ENDPOINT=https://example.com/oauth/token
OAUTH_JWKS_URI=https://example.com/.well-known/jwks.json
OAUTH_ISSUER=https://example.com
OAUTH_AUDIENCE=client-id
OAUTH_EXTRA_AUTH_PARAMS={"scope": "openid profile"}

Run the server

Start the MCP server using the standard runtime command. The server runs as a local process and accepts connections via stdio transport, which is recommended for Claude Desktop.

uv --directory . run mcp_pinot/server.py

Security notes to consider before exposing the server: bind the HTTP transport to 0.0.0.0 with care, or prefer stdio transport for Claude Desktop usage. You can bind to 127.0.0.1 via MCP_HOST=127.0.0.1 or enable TLS by setting MCP_SSL_KEYFILE and MCP_SSL_CERTFILE.

Claude Desktop integration

To integrate with Claude Desktop, configure Claude to launch the MCP server using the stdio transport. You provide the path to the uv executable and the script that starts the server.

{"mcpServers": {"pinot_mcp": {"command": "/path/to/uv", "args": ["--directory", "/path/to/mcp-pinot-repo", "run", "mcp_pinot/server.py"]}}}

Run Pinot Quickstart (optional)

You can start a Pinot QuickStart container for testing. This step is optional and helps you verify the MCP server against a live Pinot cluster.

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

Query the MCP server

With the server running, you can exercise the MCP tools using your chosen MCP client. The quickstart checks the available tools and queries the airlineStats table.

uv --directory . run examples/example_client.py

Available tools

list_tables

Fetch and display the list of Pinot tables

fetch_metadata

Retrieve table schemas, segments, and metadata from Pinot

execute_readonly_sql

Run read-only SQL queries against Pinot and return results

view_index_metadata

Inspect index and column-level metadata for Pinot tables