AndroidMCP Framework

A Model Context Protocol (MCP) server and CLI that gives coding agents Android development capabilities: build, install, and launch on emulators and physical devices; semantic UI automation; logcat/crash diagnostics; project discovery; change-aware testing intelligence.

Testing intelligence is enabled by default alongside device, ui-automation, session-management, doctor, and workflow-discovery. Tools such as analyze_test_project, audit_screen, save_test_case, and write_test_report are available without enabling another workflow. See workflow docs.

Install

npm install -g androidmcp-framework@latest
androidmcp-framework doctor
# Update to the latest global release and clear npm cache
amf update
# Short alias (also installed by npm)
amf doctor

Or run on demand with no global install: npx -y androidmcp-framework@latest mcp. The amf update command updates a global npm installation; if you use npx, rerun it with @latest to fetch the latest version. If an update is installed, the command clears only npm's _npx execution cache under the configured npm cache directory (normally ~/.npm/_npx on macOS/Linux); it does not clear the shared package-download cache.

Related MCP server: Android Project MCP Server

Connect an MCP client

{
  "mcpServers": {
    "androidmcp-framework": {
      "command": "npx",
      "args": ["-y", "androidmcp-framework@latest", "mcp"]
    }
  }
}

See coding agent setup for Claude Code, Codex, Gemini CLI, Antigravity, and VS Code/GitHub Copilot instructions. Android Studio's documented MCP client requires HTTP, while this server currently exposes stdio only; see supported clients.

Initialize an app project

From the Android or Flutter repository root:

androidmcp-framework setup
# Generate the agent skill later, without rerunning setup
androidmcp-framework skill-gen --agent claude

This creates .androidmcp-framework/config.yaml, asks which coding agent you use in an interactive terminal, and writes a project-local SKILL.md into that agent's skills folder. Supported choices include Claude Code, Codex, Gemini CLI, Antigravity, Cursor, GitHub Copilot, and a generic agent. Existing skill files are never overwritten. You can also run androidmcp-framework skill-gen or npx -y androidmcp-framework@latest skill-gen --agent codex independently. See coding-agent skills. If existing data remains under .android-build-mcp/ or .androidbuildmcp/, inspect it and run androidmcp-framework setup --migrate to copy files without overwriting existing content. The old directory is not deleted automatically.

All project-specific framework data is kept inside .androidmcp-framework/. Screenshots are saved under .androidmcp-framework/artifacts/screenshots/, raw accessibility hierarchy snapshots under .androidmcp-framework/artifacts/snapshots/, and other evidence under .androidmcp-framework/artifacts/. screenshot returns the absolute saved image path with the image; snapshot_ui saves the full tree and returns a compact summary by default. Test-case definitions and timestamped reports remain under testcases/ and test-reports/. The workspace root is discovered by walking upward to the nearest .androidmcp-framework/config.yaml or .git marker, with the current directory as fallback. Generated artifacts are local outputs and are ignored by Git by default.

Local checkout config

Build with npm ci && npm run build, then configure the MCP client to launch the built entry point build/cli/index.js mcp. Use an absolute path to your own checkout; do not copy machine-specific paths from examples.

How it's built

• UI automation: JavaScript/TypeScript plus Android SDK platform-tools (adb) only. The optional Python uiautomator2 bridge has been removed; no Python runtime or scripts/ directory is required.

• Device targeting: emulators and physical devices are unified through ADB. Explicit target, session default, then single connected target are tried in that order.

• MCP transport: stdio for local coding agents. Streamable HTTP is not implemented yet.

• Tools: one TypeScript module per tool under src/tools/<workflow>/.

Development

npm ci
npm run build
npm run typecheck
npm test

TypeScript compiles from src/ to generated build/. Do not commit generated build/ or stale dist/ output.

Testing framework

The testing-intelligence workflow is enabled by default: it analyzes Native Android and Flutter workspaces, discovers nested Flutter packages, saves custom instructions and test cases, audits screens, and writes timestamped Markdown/JSON reports under .androidmcp-framework/test-reports/YYYY-MM-DD/HHmmss/. test_device routes Flutter unit/widget tests through flutter test (kind: "unit") and can run device integration tests with flutter test -d <device-id> integration_test when integration_test/ exists. See Testing Framework, Autonomous test intelligence and execution reliability, Change-aware autonomous test planning, Unified E2E run and device regression, Phases 11–15, Phases 16–20, and Phases 24–30, and Phases 31–40, and Phases 41–50, and Phases 51–60. validate_test_evidence_bundle checks multiple reports for freshness, matching Git HEAD provenance, clean working-tree state, required suites, and passing outcomes. The run_unified_test_run tool coordinates selected native/Flutter suites and saved UI cases under one resumable run ID and writes one strict-gated report. The inspect_test_runtime tool provides a read-only overview of project config, run-lock metadata, resumable manifests, and the latest report. The plan_change_aware_test_run tool connects Git changes, saved test cases, project instructions, and recent failures to produce a reviewable plan and identify unmapped changed files without executing tests. The analyze_test_quality tool combines test-matrix inventory, changed-file LCOV coverage, historical flaky-test signals, and optional baseline regression comparison in one read-only report. evaluate_test_quality_gate applies optional changed-file coverage thresholds and baseline regression policy. run_test_suite_matrix previews or sequentially executes selected project-native Flutter/Gradle suites, with execution opt-in and timestamped evidence.

License

MIT