The read path is the one most people want: list the tables, read the schema, run the SELECT, get a page of rows rather than an unbounded dump into the context. The write path is deliberately two calls — every schema and table-config change previews by default and applies only when handed the preview's one-time token, and the documentation is explicit that a clean preview is not a promise Pinot will accept the write. Segment metadata is the part that is genuinely hard to get any other way.
A Python server for an Apache Pinot cluster: read-only SQL through the broker, table, schema and segment metadata through the controller, and schema and table-config changes that must be previewed first and then confirmed with a one-time token.
- read_query runs one read-only statement — a single SELECT, or WITH … SELECT — and anything else is rejected before it reaches Pinot; results come back as a bounded page with limit and offset
- list_tables for what is visible, get_schema for dimensions, metrics, time and primary keys, and get_table_config for indexing, retention, tenant and ingestion settings
- get_table_size reports a table's storage footprint, reported and estimated
- Segment-level detail a SQL client will not give you: list_segments names them grouped by OFFLINE and REALTIME, list_segment_metadata pages through rows, sizes and time boundaries, and get_segment_index_metadata shows which indexes each column carries in one segment
- create_schema, update_schema, create_table_config and update_table_config all default to dry_run=true, and applying takes the preview's short-lived, one-time confirmation_token
- reload_table_filters previews or applies the configured table-filter YAML without a restart, so what the server can see changes in place
- test_connection runs three checks — the broker connection, a trivial SELECT 1, and a controller table listing — so a misconfiguration reads as a diagnosis rather than a failed query
- Every tool advertises typed input and output schemas plus risk annotations, and large query, table and segment responses are paged with continuation metadata instead of filling the context
Published on PyPI as mcp-pinot-server and as the container image ghcr.io/startreedata/mcp-pinot. It needs both Pinot endpoints: PINOT_CONTROLLER_URL for metadata and table operations, defaulting to http://localhost:9000, and PINOT_BROKER_URL for queries, defaulting to http://localhost:8000. Authentication is PINOT_USERNAME with PINOT_PASSWORD, or PINOT_TOKEN, which wins when both are set. Stdio is the default; MCP_TRANSPORT=http serves over HTTP, where the server refuses a non-loopback bind unless AUTH_PROVIDER is active and a wildcard bind additionally needs an explicit MCP_ALLOWED_HOSTS list. PINOT_USE_MSQE controls the multi-stage query engine and is on by default.