Triage failing Maestro test runs by pulling failure reasons, screenshots, and logs directly into your AI assistant for automated debugging.
Also known as RubenGlez/devicecloud-mcp, devicecloud-mcp
- Stars
- 0
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 0.3.3
- Last commit
- Nov 8, 2026
- License
- MIT
What is devicecloud MCP?
devicecloud is an MCP server. Triage failing Maestro test runs by pulling failure reasons, screenshots, and logs directly into your AI assistant for automated debugging. It exposes 10 tools, such as diagnose_run, suite_health, list_uploads.
Summary generated from the project's README
About devicecloud MCP server
Debugging failing Maestro test runs by pulling failure reasons, screenshots, and logs directly into your AI assistant is what this server enables. It allows developers to triage mobile automation failures without manually navigating the DeviceCloud web dashboard. By connecting to the DeviceCloud REST API, the server provides an AI agent with the necessary evidence to identify root causes and suggest code fixes.
Users can integrate this server with clients like Claude Code, Cursor, Claude Desktop, or Windsurf using an API key. The server runs locally via npx and is read-only, meaning it cannot trigger new billable runs or cancel existing ones. It provides specific tools to diagnose runs, download HTML reports with highlighted screenshots, and extract raw artifacts like video and logs.
Beyond simple debugging, the server helps maintain test suite quality. It can rank suite health by classifying flows as healthy, flaky, broken, or regression. This helps teams prioritize which failures to address first based on pass-rate analytics and historical run data.
What you can do with it
- 1Prioritize test suite repairsIdentify which mobile flows are regressions or flaky to determine what to fix first.
- 2Analyze historical flow performanceCheck the pass rate and run history for a specific Maestro flow file to distinguish between flakes and broken code.
- 3Retrieve debugging artifactsDownload and unzip HTML reports that contain highlighted failure screenshots for visual debugging.
Written from the project's README. Every use case is checked against a quote from it.
How to install devicecloud MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall devicecloud MCP in Claude Code
$ claude mcp add --env 'DEVICE_CLOUD_API_KEY=<YOUR_DEVICE_CLOUD_API_KEY>' devicecloud-mcp -- npx -y devicecloud-mcpInstall devicecloud MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"devicecloud-mcp": {
"command": "npx",
"args": [
"-y",
"devicecloud-mcp"
],
"env": {
"DEVICE_CLOUD_API_KEY": "<YOUR_DEVICE_CLOUD_API_KEY>"
}
}
}
}Install devicecloud MCP in VS Code
.vscode/mcp.json
{
"servers": {
"devicecloud-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"devicecloud-mcp"
],
"env": {
"DEVICE_CLOUD_API_KEY": "<YOUR_DEVICE_CLOUD_API_KEY>"
}
}
}
}Install devicecloud MCP in VS Code CLI
$ code --add-mcp '{"name":"devicecloud-mcp","type":"stdio","command":"npx","args":["-y","devicecloud-mcp"],"env":{"DEVICE_CLOUD_API_KEY":"<YOUR_DEVICE_CLOUD_API_KEY>"}}'Install devicecloud MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"devicecloud-mcp": {
"command": "npx",
"args": [
"-y",
"devicecloud-mcp"
],
"env": {
"DEVICE_CLOUD_API_KEY": "<YOUR_DEVICE_CLOUD_API_KEY>"
}
}
}
}Install devicecloud MCP in Codex
$ codex mcp add devicecloud-mcp --env 'DEVICE_CLOUD_API_KEY=<YOUR_DEVICE_CLOUD_API_KEY>' -- npx -y devicecloud-mcpInstall devicecloud MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.devicecloud-mcp] command = "npx" args = ["-y", "devicecloud-mcp"] [mcp_servers.devicecloud-mcp.env] DEVICE_CLOUD_API_KEY = "<YOUR_DEVICE_CLOUD_API_KEY>"
Install devicecloud MCP in Gemini CLI
$ gemini mcp add -s user -e 'DEVICE_CLOUD_API_KEY=<YOUR_DEVICE_CLOUD_API_KEY>' devicecloud-mcp npx -- -y devicecloud-mcpInstall devicecloud MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"devicecloud-mcp": {
"command": "npx",
"args": [
"-y",
"devicecloud-mcp"
],
"env": {
"DEVICE_CLOUD_API_KEY": "<YOUR_DEVICE_CLOUD_API_KEY>"
}
}
}
}devicecloud MCP tools 10
Detected from the READMEdiagnose_runsuite_healthlist_uploadsget_upload_statusget_resultsget_junit_reportget_html_reportdownload_artifactslist_flow_analyticsget_flow_runs
| diagnose_run | — | |
| suite_health | — | |
| list_uploads | — | |
| get_upload_status | — | |
| get_results | — | |
| get_junit_report | — | |
| get_html_report | — | |
| download_artifacts | — | |
| list_flow_analytics | — | |
| get_flow_runs | — |
Configuration
DEVICE_CLOUD_API_KEYRequiredSecretDeviceCloud API key — generate one at console.devicecloud.dev/settings
| Name | Description | |
|---|---|---|
| DEVICE_CLOUD_API_KEY | DeviceCloud API key — generate one at console.devicecloud.dev/settings | RequiredSecret |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubdevicecloud-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 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
- 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-mcp
Add -s user to make it available in every project instead of only the current one.
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 |
|---|---|
diagnose_run |
Start here. One-call triage of a run (uploadId or name): folds retries per flow and returns failed flows with fail reasons, durations, and auto-downloaded failure-screenshot paths, plus a passed/failed/flaky summary and suggested next steps. Set includeReport: false to skip the screenshot download; outputDir sets where the report extracts (default /tmp). |
suite_health |
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_flow_analytics (platform, appId, days, startDate, endDate, tags). |
list_uploads |
List recent uploads. Filter by name (* wildcard), from, to, limit, offset. |
get_upload_status |
Overall status + per-test status, duration, failReason. Provide uploadId or name. |
get_results |
Per-flow rows for one upload: id, test_file_name, status, fail_reason, duration_seconds, retry_of. Optional client-side status filter. |
get_junit_report |
Raw JUnit XML for an upload. |
get_html_report |
Downloads + auto-unzips the HTML report. Returns the extraction dir and an inventory with failureScreenshots[] highlighted (these are the highest-signal debugging artifact). |
download_artifacts |
Zip of raw artifacts (logs, screenshots, video). results: "FAILED" (default) or "ALL". Saves to /tmp by default; not auto-unzipped. |
list_flow_analytics |
Per-flow pass rate, run counts, avg duration over a lookback window (default 14 days). Useful to tell flakes from genuinely-broken flows. |
get_flow_runs |
Individual run history for one flow file (fileName required). Returns status, duration, failReason, and the uploadId each run belongs to. Use to drill into a specific flow after list_flow_analytics. |
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.
devicecloud MCP questions
How do I add devicecloud MCP to Claude Code?
Run claude mcp add --env 'DEVICE_CLOUD_API_KEY=<YOUR_DEVICE_CLOUD_API_KEY>' devicecloud-mcp -- npx -y devicecloud-mcp in your terminal. Add --scope user to make it available in every project.
How do I add devicecloud MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does devicecloud MCP provide?
It exposes 10 tools, including diagnose_run, suite_health, list_uploads, get_upload_status, get_results.
Can this server trigger new test runs?
No, the server is read-only. Triggering and re-running tests must be handled through your CI or the DeviceCloud dashboard.
How do I install the server?
The server runs on demand via npx and requires Node.js 22 or higher.
What information can the assistant retrieve from a failed run?
The assistant can access failure reasons, failure screenshot paths, JUnit XML reports, and raw artifacts like logs and video.
How can I distinguish between flaky tests and broken ones?
You can use the suite health and flow analytics tools to classify flows as healthy, flaky, broken, or regression based on pass-rate analytics.