PI API MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供用于与 PI 仪表板 API 交互的标准化工具和资源。此实现使 Claude 和其他 MCP 兼容的 AI 助手能够安全地访问和管理 PI 仪表板资源，包括类别和图表。

将 PI 与 MCP 结合使用

以下演示了完成设置后此 MCP 服务器的典型使用场景。

初始身份验证：

• 执行以下说明以建立连接：

确保 PI API MCP 服务器正在运行
将 API URL 设置为 http://localhost:8224/pi/api/v2
使用 authenticate 工具获取身份验证指导
检查连接状态以验证一切正常
从仪表板列出两个图表

图表分析：

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

检索图表 ID 450 的元数据
从 ID 450 提取图表 JSON 数据
识别与声明相关的图表 ID
获取已识别图表的 JSON 数据
分析数据以生成可操作的见解

示例输出：

安装

通过 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: 通过检查示例实体获取可用于过滤的属性列表

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

连接管理

• 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

请使用 set-api-url 工具将 PI API URL 设置为 http://localhost:8224/pi/api/v2

身份验证

请帮助我对 PI API 进行身份验证。

我有一个令牌。请使用 keep-session-alive 工具和我的令牌：[YOUR_TOKEN_HERE]

请检查我与 PI API 的连接是否正常工作。

使用类别

列出仪表板中的所有类别。

获取有关 ID 为 123 的类别的详细信息。

使用图表

列出仪表板中所有可用的图表。

将 ID 为 456 的图表导出为 PDF。

使用过滤器

获取图表实体的可过滤属性，以了解我可以过滤哪些字段。

使用过滤器选项列出描述包含“revenue”的图表。

使用分析提示

分析仪表板中的类别。

比较图表 123 和 456 之间的数据。

向我展示如何有效地使用此 API 的过滤器。

---

开发

本地执行

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

# 克隆存储库（SSH 或 HTTPS 选项）
git clone git@github.com:mingzilla/pi-api-mcp-server.git
cd pi-api-mcp-server

# 安装依赖项
npm install
./dependencies.sh # 安装全局依赖项以通过 "@mingzilla/pi-api-mcp-server" 启用 MCP 客户端连接

# 构建项目
npm run build

# 执行服务器
npm start

NPM 安装

# 全局安装
npm install -g @mingzilla/pi-api-mcp-server

# 通过 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)