androidmcp-framework
io.github.kshivam1177/androidmcp-framework · version 0.1.52 · 9,417 weekly npm downloads · audited 2026-11-03
Notes
Findings
No hidden-instruction or invisible-character findings in any tool, prompt, or resource description.
Claude Connectors Directory readiness
- ✅ Every tool has a title 83 of 83 tools
- ✅ Every tool declares readOnlyHint or destructiveHint 83 of 83 tools
- ✅ Tool names are 64 characters or fewer All within limit
- ❌ Descriptions avoid instructions about model behavior or other tools 21 of 83 descriptions reference other tools or tell the model what it must do: install_app_device, tap, long_press, drag and 17 more
- ✅ No hidden instructions or invisible characters in tool metadata None found
Checks the directory's published tool requirements that are visible from tools/list. Passing them does not guarantee acceptance.
Supply chain
- Install scripts: none
- npm provenance: yes
- Source repository linked: yes
- License: MIT
- Direct dependencies: 5
Tools (83)
| Name | Title | Hint | Description |
|---|---|---|---|
list_devices | List Devices | read-only | List every connected Android target - booted emulators and physical devices together, the same way `adb devices -l` does. Each entry reports id (adb serial), type ('emulator'|'physical'), state, and avdName when resolvab… |
build_device | Build (Device) | writes | Compile-only build for a Gradle module + variant (assemble<Variant>). Does not install or launch. Works identically whether you plan to target an emulator or a physical device - both use the same adb, unlike Xcode's simu… |
build_run_device | Build, Install, and Launch | writes | One-shot: build a module + variant, install it, and launch it. Resolves the target automatically - an explicit targetId wins, then the active session default, then whichever single emulator/device is connected; if more t… |
install_app_device | Install App | writes | Install an already-built APK for a module + variant onto the resolved target. Does not rebuild - run build_device first if sources changed. Pass apkPath directly to skip variant lookup entirely. |
launch_app_device | Launch App | writes | Launch an already-installed app on the resolved target. Provide packageId directly, or module/variant to look it up from the last build's APK. Uses the app's default launcher activity unless `activity` is given. |
stop_app_device | Stop App | destructive | Force-stop a running app on the resolved target (adb shell am force-stop). |
uninstall_app_device | Uninstall App | destructive | Uninstall an app (and its data) from the resolved target. |
clear_app_data_device | Clear App Data | destructive | Reset an app to first-install state on the resolved target (adb shell pm clear) - wipes the app's data and cache without uninstalling it. |
test_device | Test (Device) | writes | Run Native Android Gradle tests or Flutter tests. Native unit runs test<Variant>UnitTest and instrumented runs connected<Variant>AndroidTest. Flutter unit runs flutter test (unit + widget tests); Flutter instrumented run… |
push_file_device | Push File | writes | Copy a local file or directory onto the resolved target (adb push). |
pull_file_device | Pull File | read-only | Copy a file or directory off the resolved target onto the local filesystem (adb pull). |
snapshot_ui | Snapshot UI | read-only | Capture the current Android accessibility hierarchy and cache short-lived elementRefs. By default, saves the raw hierarchy and complete parsed element tree to .androidmcp-framework/artifacts/snapshots/ and returns a comp… |
tap | Tap | writes | Tap either a raw (x, y) point or an elementRef from the latest snapshot_ui output. Prefer elementRef - it survives minor layout shifts that would break a hard-coded coordinate. |
tap_text | Tap Text | writes | Resolve visible text/content description from Android accessibility hierarchy and tap its bounds center. Does not require OCR. Ambiguous matches fail safely. |
clear_and_type_text | Clear and Type Text | writes | Focus a field by accessibility text or coordinates, select all using Android input keycombination (Ctrl+A), delete, and type replacement text. Coordinates should be refreshed if the keyboard/layout changes. |
is_keyboard_visible | Check Keyboard Visibility | read-only | Inspect dumpsys input_method for keyboard visibility. Returns unknown if this Android/vendor build exposes no recognized field. |
long_press | Long Press | writes | Long-press either a raw (x, y) point or an elementRef from the latest snapshot_ui output. |
swipe | Swipe | writes | Swipe either by explicit start/end coordinates, or a screen-relative direction ("up"|"down"|"left"|"right") computed from the current screen size. |
drag | Drag | writes | Press-and-drag from one point to another (adb shell input draganddrop) - for reordering list items or drag targets, where a quick swipe would be interpreted as a flick instead of a hold-and-move. Endpoints can be element… |
type_text | Type Text | writes | Type text into whatever field currently has focus. If elementRef is given, taps it first to focus it, then types. Only ASCII-range and common Latin text renders reliably through adb input text - non-Latin scripts and emo… |
key_press | Key Press | writes | Send an Android key event. Accepts symbolic names (KEYCODE_BACK, BACK, ENTER), numeric strings ("4"), or integer codes (4). |
hide_keyboard | Hide Keyboard | writes | Dismiss the on-screen keyboard using KEYCODE_ESCAPE (111) by default, or KEYCODE_BACK (4) when strategy="back". |
button | Hardware Button | writes | Press a named hardware/system button: home, back, recents, power, volume_up, volume_down, menu, enter, camera. |
gesture | Gesture Preset | writes | Named system gesture presets: expand_notifications, expand_quick_settings, collapse_statusbar (all via `cmd statusbar`, no coordinates needed), swipe_up_from_bottom (home/app-switcher gesture-nav swipe), swipe_down_from_… |
screenshot | Screenshot | read-only | Capture the current screen and always save it under .androidmcp-framework/artifacts/screenshots/<targetId>-<timestamp>.png before returning the image. The text response includes the absolute saved path. |
analyze_screen_image | Analyze Screen Image | read-only | Capture a device screenshot and semantic UI tree, optionally preprocess the image with Sharp, run OCR with Tesseract when installed, and map recognized text to element bounds and elementRef values. Saves screenshot and J… |
save_screen_map | Save Screen Map | read-only | Quickly capture a screenshot and semantic Android UI hierarchy, then persist a project-specific screen map with selectors, bounds, absolute and normalized coordinates, and a fingerprint. Does not run OCR. |
analyze_screenshot | Analyze Screenshot | read-only | Prefer local Tesseract OCR on the current screenshot. If Tesseract is unavailable or fails, fall back to Android accessibility hierarchy text and bounds, so text inspection still works without OCR. Use snapshot_ui for se… |
fill_form | Fill Form | writes | Fill visible Android form fields using semantic UI selectors, optionally clear existing text, and optionally tap a uniquely identified submit button. Refreshes the hierarchy between fields. Ambiguous or missing matches f… |
run_ui_workflow | Run UI Workflow | destructive | Validate and execute a reusable JSON UI workflow from .androidmcp-framework/workflows or replay a successfully cached sequence from .androidmcp-framework/action-sequences. Successful runs are saved as reusable action seq… |
wait_for_ui | Wait For UI | read-only | Poll the UI until a condition holds, then record the latest snapshot (same caching as snapshot_ui - refs from the result are usable directly). With textContains/resourceId: waits for a matching element to appear (or disa… |
batch | Batch | writes | Run a sequence of UI actions in one MCP call: taps, typing, waits, keyboard dismissal, clear-and-type, and text assertions. Stops at the first failed action or assertion so later steps never run against an unknown UI sta… |
touch | Touch (raw down/up/move) | writes | Send a raw touch event (adb shell input motionevent) rather than a full tap/swipe gesture. Use for composing custom multi-point sequences - e.g. DOWN, several MOVEs, then UP - that the higher-level tap/swipe/drag tools d… |
learn_screen | Learn Screen | writes | Capture the current Android screen once and save a reusable screen definition, screenshot, semantic element selectors, normalized coordinates, and a basic form specification under .androidmcp-framework/screens/<screenId>… |
interact_screen | Interact with Learned Screen | writes | Execute a bounded sequence of actions against a previously learned screen without returning to the LLM between each action. Verifies the starting fingerprint by default and returns per-action results plus an optional fin… |
start_recording | Start UI Recording | writes | Start an opt-in recording of UI actions on the selected Android device. Actions and typed text are stored in the project recording file; password/OTP-like fields are automatically redacted. Do not record credentials or s… |
stop_recording | Stop UI Recording | writes | Stop the active UI recording and persist its actions and start/stop screenshots under .androidmcp-framework/. Replay it later with replay_recording. |
replay_recording | Replay UI Recording | destructive | Replay a saved start_recording/stop_recording flow. Semantic selectors are preferred; coordinate actions are scaled to the current display size. Stops on first failure by default and saves a timestamped report plus failu… |
start_log_capture | Start Log Capture | read-only | Start streaming logcat from the resolved target to a background buffer. Returns a processId - pass it to stop_log_capture to retrieve everything captured and end the stream. |
stop_log_capture | Stop Log Capture | writes | Stop a log capture started by start_log_capture and return everything buffered (tail, if very large). |
get_crash_report | Get Crash Report | read-only | Dump the dedicated logcat "crash" buffer (adb logcat -d -b crash), which holds uncaught Java/Kotlin exception traces separately from the main log. Optionally filter to lines mentioning a specific packageId. |
get_anr_trace | Get ANR Trace | read-only | Find "ANR in <package>" entries in logcat (system_server's standard signal for a hang), and try to also pull matching files from /data/anr/. The /data/anr/ read can fail with permission denied on a non-debuggable, produc… |
clear_logs | Clear Logs | destructive | Clear the on-device logcat buffer (adb logcat -c) so the next capture starts from a clean slate. |
bug_report | Bug Report | read-only | Generate a full adb bugreport (system state, logs, dumpsys output for every service) and save it under .androidmcp-framework/artifacts/bugreports/ by default. This is comprehensive but slow - budget 1-3 minutes. |
session_show_defaults | Show Session Defaults | read-only | Show the active session-default profile and its resolved values (config.yaml sessionDefaults, overlaid with any runtime overrides from session_set_defaults). Call this before your first build/run/test call in a session -… |
session_set_defaults | Set Session Defaults | writes | Set one or more session defaults for the active profile at runtime (in-memory + persisted under the state dir for this profile - not written back to config.yaml). Only the fields you pass are changed; everything else sta… |
session_clear_defaults | Clear Session Defaults | destructive | Clear runtime overrides for the active profile (or a named one) - falls back to config.yaml's static sessionDefaults on the next read, not to nothing. |
session_use_defaults_profile | Switch Session Defaults Profile | writes | Switch the active session-defaults profile - useful in a monorepo with several Gradle projects, so each can keep its own remembered projectPath/module/variant/targetId without overwriting the others. |
doctor | Doctor | read-only | Check Android development prerequisites: adb, Java, Gradle, Android SDK, emulator, build-tools and the optional Google Android CLI integration. This framework does not require Python. |
analyze_test_project | Analyze Test Project | read-only | Inspect a Native Android or Flutter workspace/monorepo, enumerate Flutter packages and Android Gradle roots, locate tests, and review changed files. Read-only; does not run builds or modify files. |
save_test_instructions | Save Test Instructions | writes | Save or update a named, human-readable test instruction under .androidmcp-framework/instructions. Existing files are never overwritten unless overwrite is explicitly true. |
write_test_report | Write Test Report | writes | Write a Markdown report and machine-readable JSON results under .androidmcp-framework/test-reports/YYYY-MM-DD/<time>-<run-id>. Redacts common secret fields and token values; never infers test success. |
save_test_case | Save Test Case | writes | Save or update a structured, machine-readable test case definition under .androidmcp-framework/testcases/. Stores pre-conditions, step actions, targets, assertions, and metadata. |
list_test_cases | List Test Cases | read-only | List all structured test cases stored in .androidmcp-framework/testcases/, optionally filtered by category. |
audit_screen | Audit Screen QA | read-only | Perform an effortless, comprehensive QA audit on the active screen: checks for UI responsiveness errors, RenderFlex overflows, layout overlap, truncated text, broken/placeholder data (null, undefined, NaN), and logcat ex… |
run_test_case | Run Test Case | writes | Quickly and effortlessly execute a saved test case from .androidmcp-framework/testcases/. Automatically executes each step, continuously audits UI responsiveness, design/layout issues, data anomalies (null/NaN/undefined)… |
analyze_changes | Analyze Changes for Testing | read-only | Analyze Git changes, recommend focused suites, and match changed paths to saved test cases with explicit file/module mappings. Uses a broad-regression fallback when coverage is uncertain; does not execute tests. |
resolve_test_instructions | Resolve Layered Test Instructions | read-only | Merge global, project, feature, and run-specific test instructions from least to most specific. Nested objects merge recursively; arrays and scalar values are overridden by more specific scopes. This resolves configurati… |
validate_test_plan | Validate Test Plan | read-only | Validate a proposed natural-language test plan before execution. Incomplete plans are returned as blocked with a reason; this tool does not execute any action. |
refresh_test_knowledge | Refresh Persistent Test Knowledge | writes | Index saved test cases, instructions, learned screens, recordings, workflows, and reports into .androidmcp-framework/test-knowledge.json. Tracks asset changes since the previous refresh, highlights test cases whose expli… |
plan_test_run | Plan Tests from a Natural-Language Request | read-only | Turn a request into a reviewable test plan using saved test cases, explicit changed-file mappings, and project test knowledge. It reuses stored steps/assertions only, lists coverage gaps, and never executes tests. |
consolidate_test_reports | Consolidate Test Reports for CI | writes | Consolidate recognized AndroidMCP workflow, replay, saved-test-case, and standard report JSON files into a truthful Markdown summary, machine-readable JSON, and JUnit XML. Only explicit passing statuses count as passed; … |
run_test_workflow | Run Change-Aware Test Workflow | writes | Plan and optionally execute saved test cases for a natural-language request. Reuses explicit saved steps, supports a plan-only preview, captures screenshot evidence for failed steps, and writes per-case plus aggregate re… |
validate_test_environment | Validate Test Environment | read-only | Preflight the Android/Flutter workspace, saved test cases, ADB availability, and target readiness before a device test workflow. Read-only: it does not build, install, launch, or interact with the app. |
run_project_tests | Run Safe Project-Native Tests | writes | Detect and reuse Flutter or Native Android test runners. Preview is the default; execution requires execute=true. Only framework-defined test tasks are invoked, never arbitrary model-provided shell commands. Writes Markd… |
generate_test_candidate | Generate a Reviewable Test Candidate | writes | Create a review-required AndroidMCP test candidate from a natural-language request, explicit acceptance criteria, and optionally proposed UI steps from a coding agent that inspected the project. Candidate steps are not t… |
aggregate_test_evidence | Aggregate Test Evidence Across Retries | writes | Build an index of screenshot, log, snapshot, recording, and other evidence references from prior reports. It never changes or deletes source evidence; missing references remain visible in the manifest. |
evaluate_test_gate | Evaluate a Test Report CI Gate | read-only | Evaluate explicit pass/fail/skipped counts from a consolidated test summary. Empty or incomplete reports do not pass by default. This returns a gate decision for CI/coding agents; it does not mutate CI settings or launch… |
plan_intelligent_tests | Plan Intelligent Change-Aware Tests | read-only | Rank existing saved tests using the request, Git diff, explicit file mappings, project instructions, and previous failure reports. Returns explainable coverage gaps and never executes tests. |
diagnose_test_failures | Diagnose Test Failures | read-only | Classify failure evidence into environment, assertion, application, test-definition, likely-flaky, or unknown categories. Retry advice is bounded to at most two retries, requires an explicit safe-to-repeat declaration, a… |
propose_selector_repairs | Propose UI Selector Repairs | read-only | Compare a stale selector with a caller-supplied current UI hierarchy and propose ranked alternatives. Never updates saved tests or executes actions. |
run_autonomous_test_cycle | Run Autonomous Testing Cycle | writes | Coordinate change discovery, explainable test selection, safe project-native test execution, failure diagnosis, immutable attempt evidence, and a strict test gate. Preview is default; execute=true explicitly opts into ru… |
analyze_test_quality | Analyze Test Quality, Coverage, and History | read-only | Build a read-only quality picture from project test markers, LCOV coverage, recent saved reports, and optional baseline/current summaries. Reports coverage as unknown when no coverage file exists; flags flaky tests only … |
evaluate_test_quality_gate | Evaluate Test Quality Policy Gate | read-only | Evaluate optional changed-file coverage and baseline-regression policies as pass/fail/incomplete. Missing coverage is incomplete rather than a pass. Read-only: this tool does not run tests or change CI configuration. |
run_test_suite_matrix | Run Safe Project Test Suite Matrix | writes | Plan or sequentially execute the available project-native Flutter or Android Gradle unit/integration suites. Preview is default; execute=true is required to run commands. Each suite result and bounded, redacted output is… |
validate_test_evidence_bundle | Validate a Multi-Report Test Evidence Bundle | read-only | Validate saved report freshness, Git HEAD provenance, working-tree cleanliness, suite coverage, and test outcomes across multiple reports. Returns pass/fail/incomplete; it does not execute tests or change files. |
run_unified_test_run | Run Unified End-to-End Test Run | writes | Coordinate native Android/Flutter suites and saved UI test cases under one durable run ID. Preview is default; execute=true opts into test commands and device actions. Writes resumable state, bounded transient retries fo… |
inspect_test_runtime | Inspect AndroidMCP Test Runtime | read-only | Read-only overview of the current project config, active-run lock, resumable run manifests, and latest test report. Returns metadata and gate summaries only; it does not execute commands or expose raw logs. |
plan_change_aware_test_run | Plan Change-Aware Autonomous Tests | read-only | Build a reviewable, change-aware test plan from Git diffs, explicit saved-test mappings, project instructions, and recent failures. Identifies unmapped code and proposes test types for human review. Read-only: never writ… |
review_test_candidate | Review and Approve a Generated Test Candidate | writes | Validate a saved generated test candidate and optionally promote it into the approved test-case directory. Approval is explicit; placeholders, unreviewed steps, missing targets, inputs, outcomes, or malformed candidate s… |
prepare_change_aware_execution_plan | Prepare a Change-Aware Unified Test Execution Plan | read-only | Connect Git change analysis and explicit saved-test mappings to the existing unified test runner. Produces a reviewable invocation with focused test IDs when mappings are complete, otherwise recommends broad regression. … |
approve_selector_repair | Review and Approve a Runtime-Verified Selector Repair | writes | Validates a proposed saved-test selector against a fresh caller-supplied accessibility hierarchy. Without approve=true it is read-only. Explicit approval rechecks the current saved step, creates a backup and audit record… |
manage_workflows | Manage Workflows | writes | List every workflow and which of its tools are currently enabled, or enable/disable a workflow for this running server session. Session-only - it does not edit .android-build-mcp/config.yaml, so restart-persistent change… |
Check your own setup
npx mcpvetter scan --liveBadge
Add this to a README:
[](https://mcpvetter.com/servers/androidmcp-framework)Publish this server?
Get the MCPVetter verified badge, a re-audit within 24 hours of every npm release, and an email whenever tools, findings, or Claude directory readiness change. $29 per server per month. You prove ownership first, free.