Pinot MCP服务器
目录
概述
它允许你
- 列出Pinot中的表、段和模式信息
- 执行只读SQL查询
- 查看索引/列级元数据
- 旨在通过Claude集成帮助业务用户
- 还有更多。
Pinot MCP在行动
请参阅下面的Pinot MCP：
正在获取元数据
获取数据，然后进行分析
提示： 你能绘制GitHub事件随时间变化的直方图吗 Pinot MCP fetching data and analyzing table
示例提示
克劳德跑步后，点击锤子🛠️ 图标并尝试以下提示：
- 你能帮我分析皮诺的数据吗？使用Pinot工具，首先查看表格列表。
- 你能绘制GitHub事件随时间变化的直方图吗
快速开始
先决条件
安装uv（如果尚未安装）
紫外线 是一个用Rust编写的快速Python包安装程序和解析器。它被设计为性能明显更好的pip的直接替代品。
curl -LsSf https://astral.sh/uv/install.sh | sh
# Reload your bashrc/zshrc to take effect. Alternatively, restart your terminal
# source ~/.bashrc安装
# Clone the repository
git clone https://github.com/startreedata/mcp-pinot.git
cd mcp-pinot
uv pip install -e . # Install dependencies
# For development dependencies (including testing tools), use:
# uv pip install -e .[dev] 配置Pinot集群
MCP服务器需要一个uvicorn配置样式 .env 根目录中的文件，用于配置Pinot集群连接。此repo包含一个示例 .env.example 假定pinot快速入门设置的文件。
mv .env.example .env配置表筛选（可选）
⚠️ 安全说明： 对于生产访问控制，请使用 Pinot的原生表级ACL （从Pinot 0.8.0+开始供应）。此MCP服务器中的表过滤是组织表和改进用户体验的便利功能，而不是安全边界。它使用尽力而为的SQL解析，不应依赖于安全性。
表过滤允许您控制哪些Pinot表通过MCP服务器可见。这有助于：
- 减少认知负荷：当您的Pinot集群有数百或数千张桌子时，请关注相关的桌子
- 多租户用户体验：对同一Pinot集群运行多个MCP服务器实例，每个实例显示不同团队或用例的不同表子集
- 环境隔离：部署仅显示特定于环境的表的不同MCP服务器实例（dev、staging、prod）
- 隐藏系统表：从最终用户视图中筛选出内部、测试或弃用的表
当启用表过滤时， 所有表格操作 被过滤以仅显示配置的表。
什么被过滤
表过滤适用于 所有MCP操作:
- 表列表 -表列表中仅显示已配置的表
- 查询执行 -检查SQL查询以确保所有引用的表（在FROM、JOIN、子查询、CTE等中）与配置的模式匹配
- 表操作 -按表名筛选直接表访问操作：
- 获取表详细信息、大小和元数据 - 获取表段和段元数据 - 获取索引/列详细信息 - 获取/更新表配置
- 架构操作 -按架构名称筛选架构操作：
- 获取/创建/更新模式 - 创建表配置
设置
复制示例配置文件：
cp table_filters.yaml.example table_filters.yaml编辑 table_filters.yaml 指定要包含哪些表：
included_tables:
- production_* # All tables starting with "production_"
- analytics_events # Specific table name
- metrics_* # All tables starting with "metrics_"在您的 .env:
PINOT_TABLE_FILTER_FILE=table_filters.yaml模式匹配
过滤器支持使用标准Unix文件名模式匹配的glob样式模式：
exact_table_name-与这张桌子完全匹配prefix_*-匹配所有以“prefix\_”开头的表*_suffix-匹配所有以“\_suffix”结尾的表*pattern*-匹配所有包含“模式”的表sharded_table_?-匹配下划线后只有一个字符的表（例如。，sharded_table_1,sharded_table_a)
查询筛选
启用筛选后，SQL查询在执行前会被检查：
- 支持的SQL功能：FROM子句、JOIN子句（INNER、LEFT、RIGHT、OUTER、CROSS）、子查询、CTE（WITH）、UNION查询、逗号分隔的表列表
- 引用标识符：支持双引号(
"table name")巴克引用(` - 架构前缀：处理模式限定的表名（例如。，
database.schema.table) - 评论：检查前删除SQL注释
筛选查询示例：
SELECT * FROM allowed_table
JOIN other_table ON allowed_table.id = other_table.id错误： Query references unauthorized tables: other_table. Allowed tables: allowed_table, prod_*
配置功能
快速验证失败：
- ⚠️ 如果
PINOT_TABLE_FILTER_FILE已配置，但文件不存在，服务器将 无法启动 带着一个FileNotFoundError - 这可以防止由于配置错误而意外显示所有表
- 筛选器文件为空或缺失
included_tables键将显示所有表（无筛选）
综合过滤：
- 所有访问表的MCP工具在执行前都会应用筛选
- 对所有表访问点进行一致的过滤
- 明确的错误消息指示哪些表与配置的模式不匹配
禁用表筛选
要禁用表筛选，请执行以下操作之一：
- 删除
PINOT_TABLE_FILTER_FILE环境变量，或 - 不要在您的
.env文件
未配置时，Pinot集群中的所有表都是可见的。
配置OAuth身份验证（可选）
要启用OAuth身份验证，请在您的 .env 文件：
必需变量（当 OAUTH_ENABLED=true):
OAUTH_CLIENT_ID：OAuth客户端IDOAUTH_CLIENT_SECRET：OAuth客户端密钥OAUTH_BASE_URL：您的MCP服务器基本URLOAUTH_AUTHORIZATION_ENDPOINT：OAuth授权端点URLOAUTH_TOKEN_ENDPOINT：OAuth令牌端点URLOAUTH_JWKS_URI：用于令牌验证的JSON Web密钥集URIOAUTH_ISSUER：令牌发行者标识符
可选变量：
OAUTH_AUDIENCE：令牌验证的预期受众声明OAUTH_EXTRA_AUTH_PARAMS：作为JSON对象的附加授权参数（例如。，{"scope": "openid profile"})
配置示例：
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"}运行服务器
uv --directory . run mcp_pinot/server.py您应该看到指示服务器正在运行的日志。
安全注意事项： - HTTP传输绑定到0.0.0.0默认情况下；更喜欢stdio为Claude Desktop传输，或将HTTP绑定到127.0.0.1通过MCP_HOST=127.0.0.1，或启用TLS(MCP_SSL_KEYFILE/MCP_SSL_CERTFILE)在暴露之前。 - 确保您正在使用mcp[cli]版本>=1.10.0，其中包括对HTTP/SSE服务器的DNS重新绑定保护。
启动Pinot快速入门（可选）
使用docker启动Pinot快速入门：
docker run --name pinot-quickstart -p 2123:2123 -p 9000:9000 -p 8000:8000 -d apachepinot/pinot:latest QuickStart -type batch查询MCP服务器
uv --directory . run examples/example_client.py此快速入门只检查所有工具并查询airlineStats表。
Claude桌面集成
打开Claude的配置文件
vi ~/Library/Application\ Support/Claude/claude_desktop_config.json添加MCP服务器条目
{
"mcpServers": {
"pinot_mcp": {
"command": "/path/to/uv",
"args": [
"--directory",
"/path/to/mcp-pinot-repo",
"run",
"mcp_pinot/server.py"
],
"env": {
// You can also include your .env config here
}
}
}
}替换 /path/to/uv 使用uv命令的绝对路径，您可以运行 which uv 为了弄清楚。
替换 /path/to/mcp-pinot 带有克隆此仓库的文件夹的绝对路径。
注意：运行服务器时必须使用stdio传输才能与Claude桌面一起使用。
您还可以在此处配置环境变量，而不是 .env 文件，以防您想作为MCP服务器连接到多个pinot集群。
重新启动克劳德桌面
Claude现在将在启动时自动启动MCP服务器，并识别新的基于Pinot的工具。
使用DXT扩展
Apache Pinot MCP服务器现在支持DXT桌面扩展文件
要使用它，您首先需要通过以下方式安装dxt
npm install -g @anthropic-ai/dxt然后可以运行以下命令：
uv pip install -r pyproject.toml --target mcp_pinot/lib
uv pip install . --target mcp_pinot/lib
dxt pack在此之后，您将在目录中获得一个.dxt文件。双击该文件将其安装在claude桌面中
开发者
- 所有工具在
Pinot类在utils/pinot_client.py
构建
用以下方式构建项目
pip install -e ".[dev]"测试
使用以下命令测试repo：
pytest构建Docker镜像
docker build -t mcp-pinot .运行容器
docker run -v $(pwd)/.env:/app/.env mcp-pinot注意：请确保您的 .env 在运行容器之前，使用适当的Pinot集群设置配置文件。