Apache Pinot MCP Server — Claude Code MCP server: setup
Connect an agent to Apache Pinot to inspect tables and run read-only SQL, with a preview step before schema and configuration changes.
claude mcp add --env PINOT_CONTROLLER_URL=<PINOT_CONTROLLER_URL> --env PINOT_BROKER_URL=<PINOT_BROKER_URL> --env PINOT_USERNAME=<PINOT_USERNAME> --env PINOT_PASSWORD=<PINOT_PASSWORD> --env PINOT_TOKEN=<PINOT_TOKEN> --transport stdio apache-pinot-mcp-server -- uvx mcp-pinot-serverWhat Apache Pinot MCP Server does
This Python MCP server gives an agent access to Apache Pinot. Its tools check connectivity, inspect tables, schemas, segments and indexes, and submit read-only SQL. Large responses are paged with continuation details rather than returned as one unbounded result.
For schema, table-config and filter changes, call the relevant tool with dry_run=true first. The preview includes a one-time confirmation token; applying the change requires user confirmation and that token. A successful preview does not ensure Pinot will accept the write.
The connection needs Pinot controller and broker URLs plus credentials. In Claude Code, one setup command is claude mcp add mcp-pinot -e PINOT_PASSWORD=<PINOT_PASSWORD> -e PINOT_TOKEN=<PINOT_TOKEN> -- uvx mcp-pinot-server. Supply the cluster addresses as well, or the server cannot connect to Pinot.
What it helps with
- check connectivity to Pinot brokers and controllers
- inspect table schemas and configuration
- run a read-only Pinot SQL query
- retrieve segment and index metadata
- preview a schema or table-config change
Example prompts for the agent
- List the Pinot tables and show the schema for
events. - Run a read-only query that counts rows by service in
events. - Preview a change to this table configuration and show me the proposed result.
How to install Apache Pinot MCP Server
Platform CLI
claude mcp add --env PINOT_CONTROLLER_URL=<PINOT_CONTROLLER_URL> --env PINOT_BROKER_URL=<PINOT_BROKER_URL> --env PINOT_USERNAME=<PINOT_USERNAME> --env PINOT_PASSWORD=<PINOT_PASSWORD> --env PINOT_TOKEN=<PINOT_TOKEN> --transport stdio apache-pinot-mcp-server -- uvx mcp-pinot-serverReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-pinot-server <command>
Platform CLI
codex mcp add apache-pinot-mcp-server --env PINOT_CONTROLLER_URL=<PINOT_CONTROLLER_URL> --env PINOT_BROKER_URL=<PINOT_BROKER_URL> --env PINOT_USERNAME=<PINOT_USERNAME> --env PINOT_PASSWORD=<PINOT_PASSWORD> --env PINOT_TOKEN=<PINOT_TOKEN> -- uvx mcp-pinot-serverReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-pinot-server <command>
Config file
{
"mcpServers": {
"apache-pinot-mcp-server": {
"command": "uvx",
"args": [
"mcp-pinot-server"
],
"env": {
"PINOT_CONTROLLER_URL": "<PINOT_CONTROLLER_URL>",
"PINOT_BROKER_URL": "<PINOT_BROKER_URL>",
"PINOT_USERNAME": "<PINOT_USERNAME>",
"PINOT_PASSWORD": "<PINOT_PASSWORD>",
"PINOT_TOKEN": "<PINOT_TOKEN>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-pinot-server <command>
Config file
{
"servers": {
"apache-pinot-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-pinot-server"
],
"env": {
"PINOT_CONTROLLER_URL": "<PINOT_CONTROLLER_URL>",
"PINOT_BROKER_URL": "<PINOT_BROKER_URL>",
"PINOT_USERNAME": "<PINOT_USERNAME>",
"PINOT_PASSWORD": "<PINOT_PASSWORD>",
"PINOT_TOKEN": "<PINOT_TOKEN>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-pinot-server <command>
Platform CLI
gemini mcp add -e PINOT_CONTROLLER_URL=<PINOT_CONTROLLER_URL> -e PINOT_BROKER_URL=<PINOT_BROKER_URL> -e PINOT_USERNAME=<PINOT_USERNAME> -e PINOT_PASSWORD=<PINOT_PASSWORD> -e PINOT_TOKEN=<PINOT_TOKEN> apache-pinot-mcp-server uvx mcp-pinot-serverReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-pinot-server <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Apache Pinot MCP Server
How do I install Apache Pinot MCP Server in Claude Code?
Run claude mcp add mcp-pinot -e PINOT_PASSWORD=<PINOT_PASSWORD> -e PINOT_TOKEN=<PINOT_TOKEN> -- uvx mcp-pinot-server. Set the password and token values for your Pinot connection.
What does Apache Pinot MCP Server do?
It lets an agent inspect Pinot metadata and run SQL that is restricted to reading data. It also provides tools to preview schema, table-config and filter changes before applying them.
How does the server handle changes to Pinot?
First call the matching tool with dry_run=true and review its preview. Applying the change requires user confirmation and the preview’s one-time confirmation_token; Pinot can still reject the write.
