Skip to main content
Glama
AndroidMCP Framework

AndroidMCP Framework

by kshivam1177

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: DroidAgentKit

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.

Runtime selector maintenance is also available through approve_selector_repair: it validates a proposed selector against a fresh accessibility hierarchy, requires explicit approval before changing a saved test, creates a backup and audit record, and still requires a real rerun for pass/fail evidence. See runtime-verified selector repair.

License

MIT

Autonomous test lifecycle

For the recommended change-aware flow from Git analysis through reviewed test candidates, explicit approval, unified execution, and evidence-backed reporting, see Autonomous test lifecycle. The framework keeps candidate, approved, and executed states separate and falls back to broad regression when explicit test mappings do not cover changed files.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      MCP server that provides AI coding agents real Android development tools—Gradle, adb, logcat, lint, crash triage—through a local, permissioned interface. Enables agents to inspect projects, run safe Gradle tasks, capture logs/screenshots, and triage crashes.
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives coding agents hands and eyes on an Android device, providing 19 tools for building, testing, installing, UI inspection, input, logs, and toolchain diagnosis. It returns concise, structured results to make the build-debug loop efficient.
      19
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Lets AI coding agents build, test, and lint Android projects with Gradle, control devices and emulators via adb, automate UI through screenshots and input injection, and use a live IDE bridge for refactoring, code inspection, and run configurations. Works with any MCP client over stdio or authenticated HTTP.
      46
      MIT