# Apache Pinot MCP Server

Connect an agent to Apache Pinot to inspect tables and run read-only SQL, with a preview step before schema and configuration changes.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 17
- Author: startreedata
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/startreedata/mcp-pinot
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/apache-pinot-mcp-server

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `PINOT_CONTROLLER_URL`, `PINOT_BROKER_URL`, `PINOT_USERNAME`, `PINOT_PASSWORD`, `PINOT_TOKEN`, `PINOT_USE_MSQE`, `MCP_TRANSPORT`, `AUTH_PROVIDER` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-server
```
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>

### Codex

**Platform CLI**
```bash
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-server
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
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-server
```
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>

## When to use it
- 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
- 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.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md