Pinot MCP Server

by startreedata

16 298 downloads Not rated yet Apache-2.0

GitHub Website

About

An MCP server for interacting with Apache Pinot, a real-time distributed OLAP datastore.

Details

License: Apache-2.0

Explore

Fail-Fast Validation:
- ⚠️ If PINOT_TABLE_FILTER_FILE is configured but the file doesn't exist, the server will fail to start with a FileNotFoundError
- This prevents accidentally showing all tables due to misconfiguration
- Empty filter files or missing included_tables key will show all tables (no filtering)

Comprehensive Filtering:
- All MCP tools that access tables apply filtering before execution
- Consistent filtering across all table access points
- Clear error messages indicate which tables don't match the configured patterns

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Pinot MCP Server

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

From the repository


uv is a fast Python package installer and resolver, written in Rust. It's designed to be a drop-in replacement for pip with significantly better performance.

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


The MCP server expects a uvicorn config style .env file in the root directory to configure the Pinot cluster connection. This repo includes a sample .env.example file that assumes a pinot quickstart setup.

bash mv .env.example .env

The server loads configuration from environment variables and from a .env file found from the current working directory. Values in .env override process environment variables, so run the server from the repository directory or pass the same variables through your process manager, container, or Claude Desktop configuration. > ⚠️ Security Note: For production access control, use Pinot's native table-level ACLs (available since Pinot 0.8.0+). Table filtering in this MCP server is a convenience feature for organizing tables and improving UX, not a security boundary. It uses best-effort SQL parsing and should not be relied upon for security. Table filtering allows you to control which Pinot tables are visible through the MCP server. This is useful for: - Reduce Cognitive Load: Focus on relevant tables when your Pinot cluster has hundreds or thousands of tables - Multi-Tenancy UX: Run multiple MCP server instances against the same Pinot cluster, each showing different table subsets for different teams or use cases - Environment Separation: Deploy different MCP server instances (dev, staging, prod) that show only environment-specific tables - Hide System Tables: Filter out internal, test, or deprecated tables from end-user view When table filtering is enabled, all table operations are filtered to show only the configured tables. Fail-Fast Validation: - ⚠️ If PINOT_TABLE_FILTER_FILE is configured but the file doesn't exist, the server will fail to start with a FileNotFoundError - This prevents accidentally showing all tables due to misconfiguration - Empty filter files or missing included_tables key will show all tables (no filtering) Comprehensive Filtering: - All MCP tools that access tables apply filtering before execution - Consistent filtering across all table access points - Clear error messages indicate which tables don't match the configured patterns To enable OAuth authentication, set the following environment variables in your .env file: Required variables (when OAUTH_ENABLED=true): - OAUTH_CLIENT_ID: OAuth client ID - OAUTH_CLIENT_SECRET: OAuth client secret - OAUTH_BASE_URL: Your MCP server base URL - OAUTH_AUTHORIZATION_ENDPOINT: OAuth authorization endpoint URL - OAUTH_TOKEN_ENDPOINT: OAuth token endpoint URL - OAUTH_JWKS_URI: JSON Web Key Set URI for token verification - OAUTH_ISSUER: Token issuer identifier Optional variables: - OAUTH_AUDIENCE: Expected audience claim for token validation - OAUTH_EXTRA_AUTH_PARAMS: Additional authorization parameters as JSON object (e.g., {"scope": "openid profile"})

Example configuration:

bash
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"}

Start Pinot QuickStart using docker:

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

Query MCP Server

bash
uv --directory . run examples/example_client.py

This quickstart just checks all the tools and queries the airlineStats table.

bash
vi ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "pinot mcp server": {
            "mcp-pinot": {
                "command": "uv",
                "args": [
                    "pip",
                    "install",
                    "-e",
                    ".",
                    "#",
                    "Install",
                    "dependencies"
                ]
            }
        }
    }
}

McpServers

{
    "mcp-pinot": {
        "command": "uv",
        "args": [
            "pip",
            "install",
            "-e",
            ".",
            "#",
            "Install",
            "dependencies"
        ]
    }
}

- Overview
- Features
- Quick Start
- Configuration Reference
- Docker Build
- Claude Desktop Integration
- Try a Prompt
- Security and Vulnerability Reporting
- Developer Notes

Overview

This project is a Python-based Model Context Protocol (MCP) server for interacting with Apache Pinot. It is built using the FastMCP framework. It is designed to integrate with Claude Desktop to enable real-time analytics and metadata queries on a Pinot cluster.

It allows you to
- List tables, segments, and schema info from Pinot
- Execute read-only SQL queries
- View index/column-level metadata
- Designed to assist business users via Claude integration
- and much more.

Pinot MCP in Action

See Pinot MCP in action below:

Fetching Metadata

Fetching Data, followed by analysis

Prompt:
Can you do a histogram plot on the GitHub events against time
Pinot MCP fetching data and analyzing table

Sample Prompts

Once Claude is running, click the hammer 🛠️ icon and try these prompts:

- Can you help me analyse my data in Pinot? Use the Pinot tool and look at the list of tables to begin with.
- Can you do a histogram plot on the GitHub events against time

Quick Start

Prerequisites

Install uv (if not already installed)

uv is a fast Python package installer and resolver, written in Rust. It's designed to be a drop-in replacement for pip with significantly better performance.

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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Table of Contents

Overview

Pinot MCP in Action

Fetching Metadata

Fetching Data, followed by analysis

Sample Prompts

Quick Start

Prerequisites

Install uv (if not already installed)

More like this

Sequential Thinking

Redis

Brave Search

Filesystem