PI API MCP Server

PI API MCP サーバー

PI Dashboard API と連携するための標準化されたツールとリソースを提供する Model Context Protocol（MCP）サーバーです。この実装により、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：2 つのチャートのデータを比較します
• 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)