PI API MCP 服务器使用说明

项目简介

本项目 'PI API MCP Server' 是一个 Model Context Protocol (MCP) 服务器实现，旨在为 Claude 等兼容 MCP 协议的 AI 助手提供访问 PI Dashboard API 的桥梁。通过此服务器，用户可以使用自然语言指令，让 AI 助手安全地访问和管理 PI Dashboard 中的资源，例如类别 (Categories) 和图表 (Charts)，从而实现数据分析、仪表盘管理等功能。

主要功能点

API URL 配置: 允许用户动态配置 PI Dashboard API 的 URL。
身份验证: 支持用户通过用户名和密码进行身份验证，安全访问 API 资源。
会话管理: 支持会话保持和注销，保障用户操作的安全性。
组织管理: 允许用户设置组织 ID，以便操作特定组织的数据。
类别管理: 提供类别的增删改查功能，包括列表展示、ID 查询、创建、更新和删除类别，以及列出类别对象。
图表管理: 提供图表的增删查功能，包括列表展示、ID 查询、删除和导出图表 (支持多种格式，如 CSV, PDF, JSON 等)。
数据导出: 支持将图表数据导出为多种格式，方便用户进行进一步分析。
分析 Prompt: 预置多种分析 Prompt 模板，例如类别分析、图表分析、图表对比和类别使用情况分析，简化用户与 AI 助手的交互。

安装步骤

推荐使用 Docker 安装：

确保您的系统已安装 Docker。
无需 MCP 服务器配置，服务器将以 Docker 容器方式运行。
配置 MCP 客户端 (例如 Claude)：按照 服务器配置 部分的说明进行配置。

本地 Node.js 环境安装 (开发或测试)：

确保您的系统已安装 Node.js 和 npm。

克隆仓库到本地：

git clone https://github.com/mingzilla/pi-api-mcp-server.git
cd pi-api-mcp-server

安装依赖：

npm install
./dependencies.sh

构建项目：
```
npm run build
```
启动服务器：
```
npm start
```

服务器配置

对于 MCP 客户端 (如 Claude)，您需要配置 MCP 服务器的连接信息。以下是配置示例 (JSON 格式)，请添加到 Claude 的配置文件中。

Docker 部署配置 (推荐):

{
  "mcpServers": {
    "pi-api": {  // 服务器名称，可以自定义
      "command": "docker", // 启动命令，这里使用 docker
      "args": [ // 启动参数
        "run",
        "-i", // 保持STDIN开放，分配TTY
        "--rm", // 容器退出后自动删除
        "-e",  // 设置环境变量
        "API_URL=http://localhost:8224/pi/api/v2", // PI API 的 URL，根据实际情况修改
        "-e",  // 设置环境变量
        "PI_API_KEY=XXXXXXXX", // PI API Key，如果需要，请替换为您的 API Key
        "mingzilla/pi-api-mcp-server" // Docker 镜像名称
      ],
      "disabled": false, // 设置为 false 启用该服务器
      "autoApprove": [ // 自动允许执行的工具，避免每次调用工具都需要手动批准
        "authenticate",
        "keep-session-alive",
        "list-categories",
        "get-category",
        "list-charts",
        "get-chart"
      ]
    }
  }
}

Node.js 本地部署配置:

{
  "mcpServers": {
    "pi-api": { // 服务器名称，可以自定义
      "command": "npx", // 启动命令，这里使用 npx
      "args": [
        "-y", // 自动确认 npx 安装包
        "@mingzilla/pi-api-mcp-server", //  MCP 服务器 npm 包名
        "--api-url", //  API URL 参数
        "http://localhost:8224/pi/api/v2", // PI API 的 URL，根据实际情况修改
        "--auth-token", //  Auth Token 参数 (可选，如果使用 API Key 认证)
        "XXXXXXXX" // 您的 Auth Token，如果使用 API Key 认证，请替换为您的 Token
      ]
    }
  }
}

配置文件位置：

macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%\Claude\claude_desktop_config.json'
Linux: 请咨询 Claude 或使用 Cline 工具查找配置文件位置。

重要提示：

'API_URL' 需要替换为您的 PI Dashboard API 的实际地址。默认情况下，可能是 'http://localhost:8224/pi/api/v2'。
如果您的 PI Dashboard API 需要 API Key 认证，您可能需要在 Docker 或 Node.js 配置中设置 'PI_API_KEY' 环境变量。
'autoApprove' 列表中的工具将自动授权执行，您可以根据需要调整此列表。

基本使用方法

启动 MCP 服务器: 根据您的安装方式 (Docker 或 Node.js) 启动 'PI API MCP Server'。
配置 MCP 客户端 (Claude): 将 服务器配置 部分生成的 JSON 配置添加到 Claude 的配置文件中。
在 Claude 中与 PI API 交互: 您可以使用自然语言指令指示 Claude 使用 'PI API MCP Server' 提供的工具和资源。

示例指令：

设置 API URL:

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

身份验证 (用户名密码):

请使用我的用户名和密码验证 PI API 身份。

列出所有类别:

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

获取 ID 为 123 的类别详情:

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

列出所有图表:

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

导出 ID 为 456 的图表为 PDF 格式:

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

分析仪表盘中的类别:

分析仪表盘中的类别。

比较图表 123 和图表 456 的数据:

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

请参考 README.md 文件获取更多详细信息和高级用法。

关键词