PI API MCP 服务器

这是一个 Model Context Protocol (MCP) 服务器，为与 PI 仪表板 API 交互提供了标准化的工具和资源。此实现使 Claude 和其他兼容 MCP 的 AI 助手能够安全地访问和管理 PI 仪表板资源，包括类别和图表。

使用 MCP 与 PI 交互

以下是在完成设置后，此 MCP 服务器的典型使用场景示例。

初始认证：

• 执行以下指令以建立连接：

Ensure the PI API MCP server is running
Set the API URL to http://localhost:8224/pi/api/v2
Use the authenticate tool for authentication guidance
Check the connection status to verify everything is working
List two charts from the dashboard

图表分析：

• 如果图表 ID 450 包含元数据信息，请使用以下提示：

Retrieve the metadata from chart ID 450
Extract the chart JSON data from ID 450
Identify chart IDs associated with claims
Obtain JSON data for the identified charts
Analyze the data to generate actionable insights

示例输出：

安装

通过 Smithery 安装

要通过 Smithery 自动安装 pi-api-mcp-server 到 Claude Desktop：

npx -y @smithery/cli install @mingzilla/pi-api-mcp-server --client claude

安装 - 使用 Docker（推荐）

• 不需要配置 MCP 服务器
• 配置 MCP 客户端文件：

{
  "mcpServers": {
    "pi-api": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_URL=http://localhost:8224/pi/api/v2",
        "-e",
        "PI_API_KEY=XXXXXXXX",
        "mingzilla/pi-api-mcp-server"
      ],
      "disabled": false,
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts", 
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

重要提示：如果在初始化时未提供 --api-url 参数，服务器会在执行任何操作之前提示您使用 set-api-url 工具配置 API URL。这种设计使得在启动时 URL 尚未确定的环境中也能灵活配置。

配置文件位置

访问您的 Claude for Desktop 应用程序配置文件的位置如下：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: 目前请使用其他工具。例如 Cline - 请求它显示 MCP 配置文件

可用工具

模式发现

• get-filterable-attributes: 通过检查样本实体来获取可用于过滤的属性列表

  获取图表实体的可过滤属性
  

连接管理

• check-connection: 检查当前 API URL 和认证是否有效
• set-api-url: 为所有请求配置基础 API URL

  将 API URL 设置为 http://localhost:8224/pi/api/v2
  

认证

• authenticate: 获取认证选项的指导
• authenticate-with-credentials: 使用用户名和密码进行认证（最后手段）
• keep-session-alive: 验证并刷新当前认证令牌（也用于基于令牌的认证）
• logout: 使当前令牌无效并结束会话
• set-organization: 为后续请求设置组织 ID

类别

• list-categories: 列出所有支持过滤的类别
• get-category: 通过 ID 获取类别
• create-category: 创建新类别
• update-category: 更新现有类别
• delete-category: 删除类别
• list-category-objects: 列出特定类别的所有对象

图表

• list-charts: 列出所有图表并支持过滤
• get-chart: 通过ID获取图表
• delete-chart: 删除图表
• export-chart: 以多种格式导出图表

可用资源

• auth://status: 获取认证状态
• categories://list: 列出所有类别
• categories://{id}: 获取特定类别
• categories://{categoryId}/objects: 获取特定类别的对象
• charts://list: 列出所有图表
• charts://{id}: 获取特定图表
• charts://{id}/export/{format}: 以特定格式导出图表

可用提示

• analyze-categories: 分析仪表板中的类别
• analyze-charts: 分析仪表板中的图表
• compare-charts: 比较两个图表之间的数据
• category-usage-analysis: 分析类别在图表中的使用情况
• use-filters: 展示如何有效地使用此API的过滤器

Claude集成示例

以下是一些与Claude连接服务器后使用的示例查询：

设置API URL

Please use the set-api-url tool to set the PI API URL to http://localhost:8224/pi/api/v2

认证

Please help me authenticate to the PI API.

I have a token. Please use the keep-session-alive tool with my token: [YOUR_TOKEN_HERE]

Please check if my connection to the PI API is working properly.

处理类别

List all categories in the dashboard.

Get details about category with ID 123.

处理图表

List all the charts available in the dashboard.

Export chart with ID 456 as a PDF.

使用过滤器

Get the filterable attributes for chart entities to understand what fields I can filter on.

List charts with description containing "revenue" using the filter option.

使用分析提示

Analyze the categories in the dashboard.

Compare data between charts 123 and 456.

Show me how to use filters effectively with this API.

---

开发

本地执行

• 注意：你也可以使用start.sh来运行开发服务器。

# Clone the repository (SSH or HTTPS option)
git clone git@github.com:mingzilla/pi-api-mcp-server.git
cd pi-api-mcp-server

# Install dependencies
npm install
./dependencies.sh # Installs global dependencies to enable MCP client connection via "@mingzilla/pi-api-mcp-server"

# Build the project
npm run build

# Execute the server
npm start

NPM安装

# Global installation
npm install -g @mingzilla/pi-api-mcp-server

# Direct execution via npx
npx @mingzilla/pi-api-mcp-server --api-url "http://localhost:8224/pi/api/v2" --auth-token "XXXXXXXX"

MCP客户端配置

与桌面版Claude集成：

Node.js实现

• 执行“本地执行”部分中的说明
• 确保已执行./dependencies.sh以安装所需依赖
• 实现以下配置（注意：@mingzilla/pi-api-mcp-server引用的是通过“本地执行”安装的包）

{
  "mcpServers": {
    "pi-api": {
      "command": "npx",
      "args": [
        "-y",
        "@mingzilla/pi-api-mcp-server",
        "--api-url",
        "http://localhost:8224/pi/api/v2",
        "--auth-token",
        "XXXXXXXX"
      ],
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts",
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

本地开发

• 使用./start.sh运行服务器
• 使用指向build/index.js文件路径的配置

./start.sh

{
  "mcpServers": {
    "pi-api": {
      "command": "node",
      "args": [
        "/home/mingzilla/dev/tool-mcp-pi-api-server/build/index.js",
        "--api-url",
        "http://localhost:8224/pi/api/v2",
        "--auth-token",
        "XXXXXXXX"
      ],
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts",
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

开发检查清单

• 更新代码 -> 启动本地服务器 -> 使用指向index.js文件的路径测试本地服务器
• 更新readme.md文件 -> 修改mcpServers配置部分：docker + node + npx
• ./publish.sh - 发布到npm
• ./dockerBuild.sh -> ./dockerPublish.sh（编辑版本号以匹配package.json）-> 测试Docker配置
• 将代码推送到GitHub

许可证

MIT许可证

作者

Ming Huang (mingzilla)