devicecloud-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@devicecloud-mcp diagnose the most recent failed run"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
devicecloud-mcp
Triage failing DeviceCloud runs so your agent can fix them, without opening the dashboard.
When a DeviceCloud run goes red in CI, the reason why is buried in the web dashboard: the fail reason, the failure screenshot, the logs. This server pulls all of it straight into your editor, so your AI assistant (Claude Code, Cursor, Claude Desktop, etc.) can read the evidence, find the root cause, and fix the flow or app code. You commit, CI re-runs, and the dashboard stays closed.
DeviceCloud is a platform for running Maestro flows on real devices. Your CI triggers the runs; this server is how you debug the ones that fail.
It lets the assistant:
diagnose a run in one call: failed flows, fail reasons, failure-screenshot paths, and a passed/failed/flaky summary, ready to act on
rank suite health: classify every flow as healthy, flaky, broken, or regression over a window so you know what's worth fixing first
list recent uploads, filter by name (commit message + short SHA) or date
read per-flow status and
failReasonfor any uploadpull the JUnit XML report
download and auto-unzip the HTML report (with failure screenshots highlighted)
download raw artifacts (logs, screenshots, video) as a zip
spot flaky vs genuinely-broken flows with per-flow pass-rate analytics
drill into run history for a specific flow file
The server is read-only against the DeviceCloud REST API: no dcd CLI dependency, and nothing an agent does can trigger billable runs. Triggering and re-running tests stay with your CI; cancelling a run stays in the dashboard.
Install
Requires Node.js 22+ — check with node --version. There's no separate install step; the server runs on demand via npx.
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.
Claude Code: add it with one command
Skip editing JSON — register the server in one step:
claude mcp add devicecloud --env DEVICE_CLOUD_API_KEY=<your-key> -- npx -y devicecloud-mcpAdd -s user to make it available in every project instead of only the current one.
Related MCP server: TestPilot MCP
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
Tool | Purpose |
| Start here. One-call triage of a run ( |
| Classify every flow over a lookback window into healthy, flaky, broken, or regression, ranked worst-first, so you can tell whether a failure is worth fixing before diving in. Regressions (passing, then recently failing) come first. Same filters as |
| List recent uploads. Filter by |
| Overall status + per-test status, duration, |
| Per-flow rows for one upload: |
| Raw JUnit XML for an upload. |
| Downloads + auto-unzips the HTML report. Returns the extraction dir and an inventory with |
| Zip of raw artifacts (logs, screenshots, video). |
| Per-flow pass rate, run counts, avg duration over a lookback window (default 14 days). Useful to tell flakes from genuinely-broken flows. |
| Individual run history for one flow file ( |
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(fromget_html_report): theunzipbinary is missing or crashed. Install withbrew 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_uploadsfor your SHA: a run probably wasn't triggered for that commit. See "When uploads do and don't exist" above.
Available Tools
10 toolsdiagnose_runA
Triage one DeviceCloud run in a single call. Resolves the upload, folds retries per flow, and returns the failed flows with fail reasons, durations, and failure-screenshot paths (auto-downloaded from the HTML report), plus a passed/failed/flaky summary and suggested next steps. The highest-signal tool for debugging a red CI run — use this first, then read the screenshots and fix the flow or app code.
Inputs: name, uploadId, outputDir, includeReport.
download_artifactsA
Download raw run artifacts (logs, screenshots, videos) as a ZIP. Use when the HTML report doesn't contain enough detail (e.g. need full logcat, video recording, or non-failure screenshots).
Inputs: uploadId (required), results, outputDir.
get_flow_runsA
List individual runs for a specific Maestro flow file. Returns id, status, createdAt, durationSeconds, failReason, testUploadId, uploadName per run. Use to drill into the history of one flow — e.g. after list_flow_analytics surfaces a flaky or broken flow.
Inputs: fileName (required), appId, limit, endDate, +2 more.
get_html_reportA
Download AND auto-unzip the HTML report (HTML + screenshots + logs) for an upload. Returns the local extraction directory and an inventory of files, with failure screenshots highlighted at the top — those are typically the highest-signal artifact for debugging.
Inputs: uploadId (required), outputDir.
get_junit_reportC
Fetch the JUnit XML report for an upload. Returns raw XML.
Inputs: uploadId (required).
get_resultsA
List individual flow results for an upload. Each result includes id, test_file_name, status, fail_reason, duration_seconds, retry_of. Optional client-side status filter.
Inputs: uploadId (required), status.
get_upload_statusA
Get status summary for one upload. Returns overall status plus per-test name, status, durationSeconds, failReason. Provide either uploadId or name (most recent matching name wins).
Inputs: name, uploadId.
list_flow_analyticsA
Aggregated pass-rate and run-count analytics per Maestro flow file over a lookback window. Use to identify flaky flows (low pass_rate but many passed_runs) vs. genuinely broken flows. Returns flow_name, file_name, pass_rate, passed_runs, failed_runs, total_runs, avg_duration, last_run_at, tags, daily_data per flow.
Inputs: days, tags, appId, endDate, +2 more.
list_uploadsA
List Maestro uploads from DeviceCloud. Filter by name (supports * wildcard), date range, and pagination. Returns id, name, created_at, consoleUrl per upload.
Inputs: to, from, name, limit, +1 more.
suite_healthA
Classify every Maestro flow over a lookback window into healthy, flaky, broken, or regression, ranked worst-first, so you can tell whether a failure is worth fixing before diving in. Regressions (a flow that was passing and recently started failing) are surfaced first, since a recent change likely broke them. Use this to prioritize, then diagnose_run to fix a specific run. Filters mirror list_flow_analytics.
Inputs: days, tags, appId, endDate, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct aspect of DeviceCloud workflows: run triage, suite health, upload listing, status, results, reports, artifact download, analytics, and flow history. Detailed descriptions clearly differentiate their purposes, with no overlap.
Most tools follow a consistent verb_noun pattern (e.g., list_uploads, get_upload_status, download_artifacts). The outlier suite_health uses a noun_noun format, which slightly breaks the pattern but remains readable.
With 10 tools, the surface is well-scoped for a CI debugging and monitoring server. Each tool serves a clear and necessary function, covering key operations without redundancy or excess.
The tool set provides comprehensive coverage for diagnosing and analyzing Maestro test runs: from high-level health to per-run artifacts and historical analytics. No obvious gaps exist for typical debugging workflows.
Maintenance
Related MCP Connectors
Investigate iOS and Android crashes and failed UI tests from your coding agent.
Approved test intent, reviewed Playwright automation and run evidence, inside your editor.
Flutter in-app bug tracking, visual pin annotations, and device logs directly into your AI IDE.
Agentic AI quality engineering: run, debug and triage tests on real browsers and devices
Related MCP Servers
AlicenseBqualityBmaintenanceEnables AI assistants to interact with Sauce Labs testing platform through natural language, providing access to device cloud management, test job analysis, build monitoring, and testing infrastructure insights. Supports both Virtual Device Cloud (VDC) and Real Device Cloud (RDC) with comprehensive test analytics and team collaboration features.3410Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables AI models (Claude, ChatGPT, GitHub Copilot) to run and analyze local tests, rerun failures, and orchestrate QA workflows using existing UI and API test frameworks.13 npmMIT
- AlicenseBqualityDmaintenanceEnables AI-powered screenshot capture and UX/UI analysis of iOS simulators and Android emulators directly from your IDE.313 npm2MIT
- AlicenseAqualityBmaintenanceEnables AI agents to orchestrate Maestro mobile UI tests across multiple devices in parallel, apply composite assertions, and automatically diagnose failures with structured evidence.7MIT