devicecloud

devicecloud-mcp

ダッシュボードを開かずに、失敗した DeviceCloud の実行をトリアージし、エージェントが修正できるようにします。

CI で DeviceCloud の実行が失敗すると、その理由はウェブダッシュボードに埋もれています。失敗理由、失敗時のスクリーンショット、ログなどです。このサーバーはそれらをすべてエディターに直接取り込み、AI アシスタント（Claude Code、Cursor、Claude Desktop など）が証拠を確認して根本原因を見つけ、フローやアプリのコードを修正できるようにします。変更をコミットすると CI が再実行され、ダッシュボードを開く必要はありません。

DeviceCloud は、実機で Maestro フローを実行するためのプラットフォームです。CI が実行を開始し、このサーバーを使って失敗した実行をデバッグします。

アシスタントでは、次のことができます。

• 1 回の呼び出しで実行を診断：失敗したフロー、失敗理由、失敗時のスクリーンショットのパス、成功・失敗・不安定の概要を取得し、すぐに対応できます
• テストスイートの健全性を評価：指定した期間内のすべてのフローを健全、不安定、破損、リグレッションに分類し、どれから修正すべきかを把握できます
• 最近のアップロードを一覧表示し、名前（コミットメッセージと短縮 SHA）または日付で絞り込む
• 任意のアップロードについて、フローごとのステータスと failReason を読み取る
• JUnit XML レポートを取得する
• HTML レポートをダウンロードして自動展開する（失敗時のスクリーンショットが強調表示されます）
• 生のアーティファクト（ログ、スクリーンショット、動画）を ZIP でダウンロードする
• フローごとの成功率分析で、不安定なフローと実際に破損したフローを見分ける
• 特定のフローファイルの実行履歴を詳しく確認する

このサーバーは DeviceCloud REST API に対して読み取り専用です。dcd CLI に依存せず、エージェントの操作で課金対象の実行が開始されることもありません。テストの開始と再実行は CI で行い、実行のキャンセルはダッシュボードで行います。

インストール

Node.js 22 以降が必要です — node --version で確認してください。別途インストールする必要はありません。サーバーは必要に応じて npx で実行されます。

MCP クライアントの設定に次の内容を追加します。

{
  "mcpServers": {
    "devicecloud": {
      "command": "npx",
      "args": ["-y", "devicecloud-mcp"],
      "env": {
        "DEVICE_CLOUD_API_KEY": "<your-key>"
      }
    }
  }
}

API キーは console.devicecloud.dev/settings で取得できます。

Claude Code：1 つのコマンドで追加する

JSON を編集せずに、1 ステップでサーバーを登録できます。

claude mcp add devicecloud --env DEVICE_CLOUD_API_KEY=<your-key> -- npx -y devicecloud-mcp

現在のプロジェクトだけでなく、すべてのプロジェクトで使えるようにするには、-s user を追加します。

アシスタントを設定する

上記の設定ブロックはすべてのクライアントで共通です。異なるのはファイルの場所だけです。

Claude Code（プロジェクト単位、.mcp.json）

ツールを利用したいプロジェクトのルートにある .mcp.json に追加します。

{
  "mcpServers": {
    "devicecloud": {
      "command": "npx",
      "args": ["-y", "devicecloud-mcp"],
      "env": {
        "DEVICE_CLOUD_API_KEY": "${DEVICE_CLOUD_API_KEY}"
      }
    }
  }
}

次に、シェルのプロファイルからキーをエクスポートし、Claude Code の子プロセスに継承されるようにします。

# ~/.zshrc or ~/.bashrc
export DEVICE_CLOUD_API_KEY="<your-key>"

対話型シェルだけで設定しても不十分です。Claude Code は独自の環境から MCP を起動するため、変数をプロファイルに設定する必要があります。

Claude Code（ユーザー単位、~/.claude.json）

プロジェクトごとではなく、どこからでも使えるようにするには、同じ devicecloud ブロックを ~/.claude.json の mcpServers の下に追加します。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。保存後に Claude Desktop を再起動してください。サーバーが接続されると、チャット入力欄にツールアイコンが表示されます。

Cursor

~/.cursor/mcp.json（グローバル）またはプロジェクトルートの .cursor/mcp.json（プロジェクト単位）に追加します。

Windsurf

~/.codeium/windsurf/mcp_config.json を編集します。

その他の MCP 対応クライアント

stdio MCP サーバーに対応するクライアントでは、同じ { command, args, env } の形式を使用します。設定ファイルの場所については、クライアントのドキュメントを参照してください。

注記： OpenAI 製品（ChatGPT、Codex、Assistants API）は独自のツールプロトコルを使用しており、MCP サーバーには対応していません。

動作確認

アシスタントを再起動した後、次を実行します。

List recent DeviceCloud uploads, limit 3.

uploads 配列を含む JSON 形式の応答が表示されるはずです。代わりに DEVICE_CLOUD_API_KEY env var is required が表示された場合、変数が起動されたプロセスに渡されていません。現在のシェルだけでなく、シェルのプロファイルからエクスポートされていることを再確認してください。

利用可能なツール

ツール	目的
diagnose_run	まずはこちらを実行してください。 実行（uploadId または name）を1回の呼び出しでトリアージします。フローごとにリトライをまとめ、失敗理由、所要時間、自動ダウンロードされた失敗時のスクリーンショットのパスとともに失敗したフローを返し、成功・失敗・不安定の概要と次のステップの提案を示します。スクリーンショットのダウンロードを省略するには includeReport: false を設定します。レポートの展開先は outputDir で指定します（デフォルトは /tmp）。
suite_health	過去の期間におけるすべてのフローを正常、不安定、故障、またはリグレッションに分類し、問題の深刻度が高い順に並べます。詳しく調べる前に、失敗の修正が必要かどうか判断できます。リグレッション（以前は成功していて、最近失敗するようになったもの）が最初に表示されます。list_flow_analytics と同じフィルター（platform、appId、days、startDate、endDate、tags）を使用できます。
list_uploads	最近のアップロードを一覧表示します。name（* ワイルドカード）、from、to、limit、offset で絞り込めます。
get_upload_status	全体のステータスとテストごとのステータス、所要時間、failReason を取得します。uploadId または name を指定します。
get_results	1件のアップロードについて、フローごとの行（id、test_file_name、status、fail_reason、duration_seconds、retry_of）を取得します。任意のクライアント側 status フィルターを指定できます。
get_junit_report	アップロードの生の JUnit XML を取得します。
get_html_report	HTML レポートをダウンロードして自動展開します。展開先ディレクトリと、failureScreenshots[] を強調表示した一覧を返します（デバッグで最も重要な情報です）。
download_artifacts	生のアーティファクト（ログ、スクリーンショット、動画）の ZIP ファイルをダウンロードします。results: "FAILED"（デフォルト）または "ALL" を指定します。デフォルトでは /tmp に保存され、自動展開はされません。
list_flow_analytics	過去の期間（デフォルトは14日間）について、フローごとの成功率、実行回数、平均所要時間を取得します。不安定なフローと実際に故障しているフローを見分けるのに役立ちます。
get_flow_runs	1つのフローファイルの個別の実行履歴を取得します（fileName は必須です）。ステータス、所要時間、failReason、各実行の uploadId を返します。list_flow_analytics の後に、特定のフローを詳しく調べる際に使用します。

アップロードの命名規則

アップロードには通常、実行のきっかけとなったコミットまたはビルドの名前が付けられます。よくある命名規則では、短縮 SHA を含めます。

fix(login): handle expired session (a1b2c3d4)

特定のコミットのすべてのアップロードを検索するには、name = "*a1b2c3d4*" で絞り込みます。ワイルドカードは % ではなく * です。

アップロードが存在する場合と存在しない場合

DeviceCloud のアップロードは、CLI、CI のステップ、GitHub Action、または API から直接実行をトリガーすると作成されます。特定のコミットにアップロードがあるかどうかは、すべて CI の設定によって決まります。想定している SHA に対して list_uploads が何も返さない場合、そのコミットでは実行がトリガーされなかった可能性があります。

トラブルシューティング

• DEVICE_CLOUD_API_KEY env var is required：この変数が起動された MCP から参照できません。~/.zshrc または ~/.bashrc からエクスポートし、アシスタントを再起動してください。
• unzip failed（get_html_report の実行時）：unzip バイナリが存在しないか、クラッシュしました。brew install unzip でインストールしてください（macOS には付属しており、Linux にも通常は含まれています）。
• HTTP 401 / 403：API キーが間違っているか、無効化されています。console.devicecloud.dev/settings で再生成してください。
• SHA に対する list_uploads の結果が空：そのコミットでは実行がトリガーされなかった可能性があります。上記の「アップロードが存在する場合と存在しない場合」を参照してください。