PI API MCP Server

PI API MCP Server

一个 Model Context Protocol（MCP）服务，提供用于与 PI Dashboard API 交互的标准化工具和资源。此实现支持 Claude 和其他兼容 MCP 的 AI 助手安全地访问和管理 PI Dashboard 资源，包括类别和图表。

使用 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 自动为 Claude Desktop 安装 pi-api-mcp-server：

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：检查示例实体，获取可用于筛选的属性列表

  Get the filterable attributes for chart entities
  

连接管理

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

  Set the API URL to 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 [email protected]: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 for Desktop 集成：

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）