Pinot MCP 服务器

目录

• 概述
• 特性
• 快速开始
• Docker 构建
• Claude 桌面集成
• 尝试一个提示
• 开发者笔记

概述

该项目是一个基于Python的模型上下文协议（MCP）服务器，用于与Apache Pinot交互。它使用了FastMCP框架构建，并设计为与Claude桌面集成，以实现实时分析和元数据查询。

它允许您：

• 列出Pinot中的表、段和模式信息
• 执行只读SQL查询
• 查看索引/列级元数据
• 通过Claude集成协助业务用户
• 以及更多功能。

<a href="https://glama.ai/mcp/servers/@startreedata/mcp-pinot"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=2686442083,3991143411&fm=3081&app=31&f=PNG?w=760&h=400" alt="Apache Pinot MCP服务器的StarTree服务器" /> </a>

Pinot MCP 在行动

请参见以下Pinot MCP的实际操作：

获取元数据

获取数据并进行分析

提示： 你可以对GitHub事件随时间变化绘制直方图吗？

示例提示

一旦Claude运行起来，点击锤子图标并尝试这些提示：

• 你能帮我分析我在Pinot中的数据吗？使用Pinot工具并从查看表单列表开始。
• 你可以对GitHub事件随时间变化绘制直方图吗？

快速开始

先决条件

安装uv（如果尚未安装）

uv 是一个用Rust编写的快速Python包安装器和解析器，旨在作为pip的替代品，具有显著更好的性能。

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

# 重新加载你的bashrc/zshrc以生效。或者，重启你的终端
# source ~/.bashrc

安装

# 克隆仓库
git clone https://github.com/startreedata/mcp-pinot.git
cd mcp-pinot
uv pip install -e . # 安装依赖

# 对于开发依赖（包括测试工具），使用：
# uv pip install -e .[dev]

配置Pinot集群

MCP服务器期望在根目录中有一个uvicorn配置风格的.env文件来配置Pinot集群连接。此仓库包含一个假设为pinot快速启动设置的示例.env.example文件。

mv .env.example .env

配置OAuth认证（可选）

要启用OAuth认证，请在您的.env文件中设置以下环境变量：

必需变量（当OAUTH_ENABLED=true时）：

• OAUTH_CLIENT_ID：OAuth客户端ID
• OAUTH_CLIENT_SECRET：OAuth客户端密钥
• OAUTH_BASE_URL：您的MCP服务器基础URL
• OAUTH_AUTHORIZATION_ENDPOINT：OAuth授权端点URL
• OAUTH_TOKEN_ENDPOINT：OAuth令牌端点URL
• OAUTH_JWKS_URI：用于令牌验证的JSON Web Key Set URI
• OAUTH_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

您应该看到日志表明服务器正在运行。

启动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": {
            // 您也可以在这里包含您的.env配置
          }
      }
  }
}

将/path/to/uv替换为您uv命令的绝对路径，您可以运行which uv来确定。

将/path/to/mcp-pinot替换为您克隆此仓库的文件夹的绝对路径。

注意：您必须使用stdio传输方式运行您的服务器，以便与Claude桌面配合使用。

您还可以在此处配置环境变量，而不是在.env文件中，如果您想连接到多个作为MCP服务器的Pinot集群。

重启Claude桌面

现在，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桌面。

开发者

• 所有工具都在utils/pinot_client.py中的Pinot类中定义

构建

使用以下命令构建项目：

pip install -e ".[dev]"

测试

使用以下命令测试仓库：

pytest

构建Docker镜像

docker build -t mcp-pinot .

运行容器

docker run -v $(pwd)/.env:/app/.env mcp-pinot

注意：确保在运行容器之前已将.env文件配置为适当的Pinot集群设置。