PI API MCP 服务器使用说明

项目简介

PI API MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为 Claude 等兼容 MCP 协议的语言模型 (LLM) 提供访问 PI Dashboard API 的桥梁。通过此服务器，LLM 能够安全、便捷地获取 PI Dashboard 中的数据资源，并调用预设的工具执行特定操作，例如查询图表、分析数据等。

主要功能点

API 访问配置: 提供工具设置 PI Dashboard API 的 URL。
用户认证: 支持用户通过用户名和密码进行身份验证，安全访问 API。
会话管理: 维护用户会话，支持保持会话活跃和注销功能。
组织机构设置: 允许指定组织机构 ID，以便访问特定组织的数据。
数据资源访问: 提供对 类别 (Categories) 和 图表 (Charts) 资源的列表、详情、创建、更新和删除等操作。
图表导出: 支持将图表导出为 CSV, DOCX, XLSX, JPEG, JSON, PNG, PDF, PPTX 等多种格式。
数据分析 Prompt: 预置多种 Prompt 模板，支持 LLM 进行类别和图表的数据分析、图表对比以及类别使用情况分析。

安装步骤

本服务器推荐使用 Docker 进行安装，无需复杂的服务器配置。

确保 Docker 环境: 请先确保您的机器上已安装 Docker。
MCP 客户端配置: 您需要在 MCP 客户端（例如 Claude for Desktop）的配置文件中添加 PI API MCP 服务器的配置信息。配置文件的位置通常如下：
- macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
- Windows: '%APPDATA%\Claude\claude_desktop_config.json'

服务器配置

以下是在 MCP 客户端配置文件 ('claude_desktop_config.json') 中添加 PI API MCP 服务器配置的示例。请根据您的实际情况进行调整。

{
  "mcpServers": {
    "pi-api": {  // 服务器名称，可以自定义
      "command": "docker",  // 启动服务器的命令，这里使用 Docker
      "args": [  // 启动命令的参数
        "run",
        "-i",  // 保持 STDIN 打开，用于 MCP 通信
        "--rm", // 容器退出后自动删除
        "-e", "API_URL=http://your-pi-api-url.com/pi/api/v2", // 设置 PI API 的 URL，请替换为您的实际 API 地址
        "mingzilla/pi-api-mcp-server:latest" // Docker 镜像名称
      ],
      "disabled": false, // 设置为 false 启用该服务器
      "autoApprove": [ // 自动允许执行的工具，例如列表工具
        "list_tools"
      ]
    }
  }
}

配置说明:

'"pi-api"': MCP 服务器的名称，您可以在客户端中使用此名称来引用该服务器。
'"command": "docker"': 指定使用 Docker 命令来运行服务器。
'"args": [...]"': Docker 运行命令的参数列表：
- '"run -i --rm"': Docker 运行参数，'-i' 保持 STDIN 打开，'--rm' 容器退出后自动删除。
- '"-e", "API_URL=http://your-pi-api-url.com/pi/api/v2"': 设置环境变量 'API_URL'，指定 PI API 的根 URL。请务必将 'http://your-pi-api-url.com/pi/api/v2' 替换为您实际的 PI Dashboard API 地址。
- '"mingzilla/pi-api-mcp-server:latest"': 使用的 Docker 镜像名称和标签。
'"disabled": false': 设置为 'false' 表示启用此 MCP 服务器。
'"autoApprove": ["list_tools"]': 可选配置，允许自动执行某些工具，无需用户每次手动批准。例如，此处设置自动允许执行 'list_tools' 工具。

基本使用方法

启动 MCP 服务器: 配置好 'claude_desktop_config.json' 后，当 Claude 启动并尝试连接 MCP 服务器时，Docker 容器会自动运行。
设置 API URL: 首次使用时，如果未在 Docker 参数中配置 'API_URL'，Claude 可能会提示您使用 'set-api-url' 工具设置 API URL。您可以向 Claude 发送类似指令：'请使用 set-api-url 工具将 PI API URL 设置为 http://your-pi-api-url.com/pi/api/v2' (请替换为您的实际 API 地址)。
用户认证: 使用 'authenticate' 工具进行身份验证。例如：'请使用我的用户名 <您的用户名> 和密码 <您的密码> 登录 PI API' (请替换为您的实际用户名和密码)。
访问数据和工具: 认证成功后，即可使用各种工具和资源访问 PI Dashboard 数据。例如：
- '列出所有类别' (使用 'list-categories' 工具和 'categories://list' 资源)
- '获取 ID 为 123 的类别的详细信息' (使用 'get-category' 工具和 'categories://{id}' 资源)
- '导出 ID 为 456 的图表为 PDF 格式' (使用 'export-chart' 工具和 'charts://{id}/export/{format}' 资源)
- '分析仪表盘中的类别' (使用 'analyze-categories' Prompt)

请参考仓库 README 文件中 "Claude Integration Examples" 和 "Available Tools", "Available Resources", "Available Prompts" 部分，了解更多工具、资源和 Prompt 的使用方法。

关键词