runnerqa-mcp

Local stdio MCP server for RunnerQA — lets Claude Code, Cursor, or any MCP client create mobile test cases, generate Maestro-compatible tests, read run evidence, and propose fixes (applied only with your approval) through the RunnerQA Agent API.

Prefer the hosted MCP. If your client supports remote MCP servers with OAuth, connect with one URL and no token: claude mcp add --transport http runnerqa https://www.runnerqa.dev/api/mcp/mcp. This local stdio package is the token-based fallback for clients without remote-server support.

This local stdio fallback package is version 0.1.2.

Test execution stays local: this server never touches your simulator or device. The RunnerQA CLI (mqa pull, mqa run <test_case_id>) runs tests on your machine and reports results back to the dashboard.

Setup

1. Create an agent token on the RunnerQA dashboard → AI Integrations (rqa_agent_..., shown once).
2. Add the server to your MCP client config:

{
  "mcpServers": {
    "runnerqa": {
      "command": "npx",
      "args": ["-y", "runnerqa-mcp"],
      "env": {
        "RUNNERQA_AGENT_TOKEN": "rqa_agent_xxx",
        "RUNNERQA_BASE_URL": "https://www.runnerqa.dev"
      }
    }
  }
}

RUNNERQA_BASE_URL is optional and defaults to https://www.runnerqa.dev.

Tools

Call runnerqa_connection_status first to confirm the Agent API token is accepted, then use the others.

| Tool | What it does | |---|---| | runnerqa_connection_status | Confirm the token is accepted; report base URL + project count (count only) | | runnerqa_list_projects | List projects (platform, framework, app id) | | runnerqa_list_test_cases | List test cases (project_id optional) | | runnerqa_create_test_case | Create a test case from a plain-English flow | | runnerqa_generate_yaml | Generate validated Maestro-compatible YAML (~10-20s) | | runnerqa_get_report_summary | QA report: totals, failing tests, recommended next steps | | runnerqa_get_run_detail | One run's status, logs, and AI failure analysis | | runnerqa_search_failures | Investigate recurring failures grouped by fingerprint over a bounded recent-run window (not all-time): first/last seen, affected tests, last pass before onset, release/commit/environment context (project_id required, q/limit optional) | | runnerqa_analyze_failure | AI-explain a failed run; returns a proposed YAML fix (not applied) | | runnerqa_apply_fix | Apply a YAML fix — only after the user explicitly approves |

Security

• The MCP token is an Agent API token, not a runner token. It can create, generate, and read — it cannot run tests on your devices.
• Tokens are shown once, stored only as hashes server-side, and revocable instantly from the dashboard.
• runnerqa_apply_fix changes a test case's YAML; the server validates it against the Maestro command allowlist and keeps every version in history. MCP clients should always ask for user approval first.

License

MIT