devicecloud-mcp

A small MCP server that exposes DeviceCloud as tools that any MCP-aware assistant — Claude Code, Cursor, Claude Desktop, etc. — can call directly. DeviceCloud is a platform for running Maestro flows on real devices.

It lets the assistant:

• list recent Maestro uploads, filter by name (commit message + short SHA) or date
• read the per-flow status and failReason for any upload
• pull the JUnit XML report
• download and auto-unzip the HTML report (with failure screenshots highlighted)
• download raw artifacts (logs, screenshots, video) as a zip
• query per-flow pass-rate analytics over a lookback window
• drill into run history for a specific flow file

The server is read-only against the DeviceCloud API.

Install

Add this to your MCP client config:

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

Get your API key at console.devicecloud.dev/settings.

Configure your assistant

The config block above is the same for every client — only the file location differs.

Claude Code (project-scoped, .mcp.json)

Add to a .mcp.json at the root of any project where you want the tools available:

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

Then export the key from your shell profile so Claude Code's child process inherits it:

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

Setting it only in an interactive shell isn't enough — Claude Code spawns the MCP from its own environment, so the variable needs to be in the profile.

Claude Code (user-scoped, ~/.claude.json)

If you want it available everywhere instead of per-project, add the same devicecloud block under mcpServers in ~/.claude.json.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Restart Claude Desktop after saving — a tools icon appears in the chat input once the server connects.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json at the project root (project-scoped).

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json.

Other MCP-compatible clients

Any client that supports stdio MCP servers uses the same { command, args, env } shape. Consult the client's docs for the config file location.

Note: OpenAI products (ChatGPT, Codex, the Assistants API) use their own tool protocol and do not support MCP servers.

Verify

After restarting your assistant:

List recent DeviceCloud uploads, limit 3.

You should see a JSON-shaped response with an uploads array. If instead you get DEVICE_CLOUD_API_KEY env var is required, the variable isn't reaching the spawned process — re-check that it's exported from your shell profile (not just the current shell).

Available tools

Upload-naming convention

Uploads are typically named after the commit or build that triggered them. A common convention is to include the short SHA:

fix(login): handle expired session (a1b2c3d4)

Filter with name = "*a1b2c3d4*" to find every upload for a specific commit. The wildcard is *, not %.

When uploads do and don't exist

DeviceCloud uploads are created when you trigger a run — via the CLI, a CI step, the GitHub Action, or the API directly. Whether a given commit has an upload depends entirely on your CI setup. If list_uploads returns nothing for a SHA you expect, the run probably wasn't triggered for that commit.

Troubleshooting

• `DEVICE_CLOUD_API_KEY env var is required` — the variable isn't visible to the spawned MCP. Export it from ~/.zshrc / ~/.bashrc, restart your assistant.
• `unzip failed` (from get_html_report) — the unzip binary is missing or crashed. Install with brew install unzip (macOS ships with it; Linux usually does too).
• HTTP 401 / 403 — the API key is wrong or revoked. Regenerate it at console.devicecloud.dev/settings.
• Empty `list_uploads` for your SHA — a run probably wasn't triggered for that commit. See "When uploads do and don't exist" above.