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集群設置。