MCP Pinot

🚀 Pinot MCP Server

本项目是一个基于Python的模型上下文协议（MCP）服务器，用于与Apache Pinot进行交互。它旨在与Claude Desktop集成，以便在Pinot集群上实现实时分析和元数据查询。

目录

• 概述
• 主要特性
• 快速开始
• Docker构建
• Claude桌面集成
• 尝试提示词
• 开发者说明

概述

本项目是一个基于Python的模型上下文协议（MCP）服务器，用于与Apache Pinot进行交互。它旨在与Claude Desktop集成，以便在Pinot集群上实现实时分析和元数据查询。

它允许你：

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

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 git@github.com:startreedata/mcp-pinot.git
cd mcp-pinot
uv pip install -e . # 安装依赖

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

配置Pinot集群

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

mv .env.example .env

运行服务器

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 tests/test_service/test_pinot_quickstart.py

此快速启动仅检查所有工具并查询airlineStats表。

📦 Claude桌面集成

打开Claude配置文件

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

添加MCP服务器条目

{
  "mcpServers": {
      "pinot_mcp_claude": {
          "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 替换为你克隆此仓库的文件夹的绝对路径。

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

重启Claude桌面

Claude现在将在启动时自动启动MCP服务器，并识别新的基于Pinot的工具。

🔧 开发者说明

• 所有工具都在 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集群设置。