PI API MCP 服务器

铁匠徽章

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

将 PI 与 MCP 结合使用

下面演示了设置完成后此 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

示例输出：

示例响应.png

安装

通过 Smithery 安装

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

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

Related MCP server: Hass-MCP

安装 - 使用 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

验证

身份验证：获取有关身份验证选项的指导
authentic-with-credentials ：使用用户名和密码进行身份验证（最后的选择）
keep-session-alive ：验证并刷新当前身份验证令牌（也用于基于令牌的身份验证）
logout ：使当前令牌无效并结束会话
set-organization ：设置后续请求的组织 ID

类别

list-categories ：列出所有支持过滤的类别
get-category ：通过 ID 获取类别
create-category ：创建一个新类别
update-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} ：以特定格式导出图表

可用提示

分析类别：分析仪表板中的类别
分析图表：分析仪表板中的图表
compare-charts ：比较两个图表之间的数据
类别使用分析：分析图表中类别的使用方式
use-filters ：展示如何通过此 API 有效地使用过滤器

克劳德积分示例

以下是连接服务器后与 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 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 许可证

作者

明皇（mingzilla）