The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the MobiLoop listing page.
Guarded MCP servers for agentic mobile build-test-fix loops.
Documentation site | Security model | Tool reference
MobiLoop MCP is a controlled tool layer between an AI coding agent and a real mobile development environment. It lets an MCP client read and patch a mobile project, build it, install it on Android or iOS targets, drive the app through Appium, verify logs/screens/API results, remember known app-flow checkpoints, and produce evidence-based reports.
The name reflects the core contract: mobile work should run through a measurable loop of change, build, device execution, verification, and evidence-backed triage.
It is built for the workflow where the agent does not just write code. It builds, runs, tests, observes, classifies failures, and hands back evidence. An agent can still use the separate guarded code tools to patch and retest, but that patch step is intentionally outside the default orchestrator.
Today, MobiLoop provides guarded build-test-verify loops and evidence-based failure classification. Fully automated patch-and-retest is intentionally kept outside the default orchestrator until stricter approval, rollback, and review controls are enabled.
adb/emulator tools and iOS xcrun simctl/xcodebuild tools are separated.This project provides MCP tools for this architecture:
The server does not claim that a test passed because a model says so. A pass should be backed by tool output: command exit codes, screenshots, page source, log checks, API assertions, and recorded loop iterations.
Install only what your target app needs.
| Workflow | Host | Required tools |
|---|---|---|
| MCP runtime | macOS, Linux, Windows | Node.js 20+ |
| Android build/test | macOS, Linux, Windows | Android SDK, adb, emulator or physical device, Java/Gradle as needed, Appium 2, UiAutomator2 driver |
| Flutter Android | macOS, Linux, Windows | Flutter SDK, Android SDK, Appium for UI flows |
| React Native Android | macOS, Linux, Windows | Node/npm, Android Gradle toolchain, Android SDK, Appium |
| iOS simulator | macOS only | Xcode, xcrun simctl, iOS Simulator, Appium 2, XCUITest driver |
| Docker MCP runtime | macOS, Linux, Windows | Docker, plus host-side mobile tools when driving devices |
Start Appium before Appium or flow replay tools:
Local Appium installs also work:
For Android, make sure the Appium process can see:
For an already-running Genymotion device, add its Android SDK platform tools to PATH, then
verify the device before starting a flow:
Run the all-in-one MCP server:
For development:
When an MCP client cannot expose the server as callable tools, use the CLI wrapper:
Inspect tool policy metadata:
The same metadata is available inside MCP through policy.list_tools.
Call any tool directly:
Generate scenario candidates:
Use this for local development and simpler MCP clients.
Use split servers when you want tighter policy boundaries per responsibility.
All binaries are listed below.
| Binary | Scope |
|---|---|
mobiloop | CLI wrapper for listing tools, calling tools, and generating scenarios |
mobiloop-mcp | All tools |
mobiloop-code-mcp | Code and git tools |
mobiloop-env-mcp | Environment preflight and compatibility matrix |
mobiloop-build-mcp | Dependency, lint, test, and APK build tools |
mobiloop-device-mcp | Android adb and emulator tools |
mobiloop-ios-mcp | iOS simulator and Xcode tools |
mobiloop-appium-mcp | Appium UI automation tools |
mobiloop-verify-mcp | Assertions and evidence collection |
mobiloop-flow-mcp | Source-flow analysis and checkpoint replay |
mobiloop-loop-mcp | Iteration records and reports |
mobiloop-ci-mcp | Artifact manifests, GitHub summaries, PR comments |
mobiloop-orchestrator-mcp | Android and iOS build-install-test-verify loops |
mobiloop-security-mcp | Static mobile security scan, test plan, scan comparison, release gate |
Secure mode does not read configuration from the project directory. Set workspace and Appium values in the host environment:
For a host-controlled file configuration, copy the example and point to it explicitly:
Or point to it explicitly:
AGENTIC_MOBILE_MCP_CONFIG and AGENTIC_MOBILE_WORKSPACE_ROOT are still accepted as legacy fallbacks, but new projects should use the MOBILOOP_* names.
Common fields:
| Field | Default | Purpose |
|---|---|---|
securityMode | secure | Secure ignores project-local config; trusted enables explicit overrides |
workspaceRoot | current working directory | Mobile app workspace the MCP server may access |
artifactsDir | .mobiloop | Evidence, logs, screenshots, reports, flow memory |
runId | unset | Optional run identifier; writes artifacts under .mobiloop/runs/<id> |
maxCommandMs | 120000 | Default command timeout |
maxOutputBytes | 1048576 | Output cap for command tools |
maxFixAttempts | 3 | Suggested fix-loop limit |
maxTestIterations | 5 | Orchestrator loop limit |
maxRuntimeMinutes | 30 | Suggested total runtime limit |
allowedBranchPattern | ^feature/ai-[A-Za-z0-9._/-]+$ | Branches where commit tools are allowed |
appiumServerUrl | http://127.0.0.1:4723 | Trusted-mode Appium endpoint; secure mode uses host environment |
adbPath | adb | Android Debug Bridge path |
emulatorPath | emulator | Android emulator CLI path |
xcrunPath | xcrun | iOS simulator CLI path |
xcodebuildPath | xcodebuild | Xcode build CLI path |
sqlitePath | sqlite3 | SQLite CLI path for read-only assertions |
apiAllowlist | localhost only | URLs allowed for API verification |
appiumAllowlist | localhost only | Trusted-mode Appium origin allowlist |
forbiddenPathGlobs | secret-like defaults | Files blocked from read/write operations |
toolPolicies | built-in defaults | Trusted-mode per-tool risk and approval metadata overrides |
requireApproval | true in secure mode | Require approval payloads for high-impact tools |
redactArtifacts | true | Redact common secrets and PII from text artifacts and text responses |
MOBILOOP_ARTIFACTS_DIR may point to a dedicated host-controlled evidence mount, such as /artifacts in the read-only Docker security server.
Environment variables override selected fields:
The config schema is available at schema/mobiloop.config.schema.json. See docs/CONFIGURATION.md.
Approval payloads use this shape:
MOBILOOP_WORKSPACE_ROOT at your mobile app.security.scan_source and security.generate_test_plan.env.preflight and flow.analyze_from_code.security.release_gate before calling a fix ready for release.v0.1.0-alpha.10 was validated against an installed MiniTakip Android application on a
Genymotion Galaxy S24 running Android 15. The non-mutating proof used MobiLoop to discover the
ADB target, create an Appium 3 UiAutomator2 session, capture a screenshot and page-source XML,
read the accessibility tree, then close the session. It did not enter form data, create records,
or delete application data.
Direct W3C capabilities are accepted by appium.create_session as shown below. MobiLoop wraps
them in the WebDriver capabilities envelope before sending them to Appium:
After creating a session, use appium.observe_screen and appium.get_accessibility_tree for
evidence, then always call appium.delete_session. A successful session only proves the selected
screen and assertions; it does not claim that an entire product journey has passed.
For a Flutter Android app, the rough tool sequence is:
orchestrator.run_android_validation_loop runs a bounded Android loop across build, install, Appium, verification, evidence, and iteration records.
Minimal shape:
See examples/android-validation-loop.json.
orchestrator.run_ios_validation_loop runs a bounded iOS simulator loop across xcodebuild, simulator boot, app install/launch, Appium XCUITest, verification, evidence, and iteration records.
Minimal Flutter shape:
See examples/flutter-ios-validation-loop.json and docs/QUICKSTART_FLUTTER.md.
buildSettings and xcodebuildArgs are forwarded to ios.build_app, so projects can handle host-specific simulator requirements such as Apple Silicon arm64 simulator builds or custom DerivedData settings without leaving the MCP loop.
MobiLoop can generate candidate E2E scenarios from the app source so the agent starts from a concrete test plan instead of an empty screen.
The output includes priorities, candidate steps, assertions, source references, and limitations. Treat these as executable candidates: the agent should run them through Appium, collect evidence, and refine them into stable checkpoint paths.
For scripted execution without writing custom client code:
Flow memory makes repeated mobile tests faster without pretending that setup screens passed.
The screen signature is built from Appium page source:
This data is persisted under:
With runId enabled, the same file lives under .mobiloop/runs/<runId>/flow/memory.json.
At a stable screen:
At the next screen:
Record the passing path:
Plan without executing:
Execute:
Supported replay actions:
appium.tap_by_textappium.tap_by_accessibility_idappium.tap_by_resource_idappium.tap_coordinatesappium.type_textappium.swipeappium.go_backappium.wait_for_visibleappium.assert_visiblePrefer semantic actions. Coordinates should be the last fallback.
See examples/flow-memory-replay.json.
The recommended Docker model is:
Build:
Published GHCR image:
Run as an MCP stdio server:
See docs/DOCKER.md.
Defaults are intentionally conservative.
workspaceRoot after symbolic-link resolution.feature/ai-* by default.apiAllowlist..mobiloop, unless the host deliberately provides a dedicated MOBILOOP_ARTIFACTS_DIR mount.Default blocked paths include:
.env, .env.**.keystore, *.jks, *.p12*.mobileprovisionGoogleService-Info.plistgoogle-services.jsonsecret or credentialSecure mode enforces approval for high-impact operations such as dependency installation, lint/test/build commands, device interaction, patches, commits, pushes, and PR creation.
MobiLoop exposes machine-readable policy metadata through mobiloop list-tools --json; see docs/TOOL_REFERENCE.md.
See docs/SECURITY.md.
The default artifact directory is:
When runId or MOBILOOP_RUN_ID is set, artifact writers use a run-scoped root:
Typical contents:
| Directory | Contents |
|---|---|
build/ | dependency, lint, test, and APK build logs |
screenshots/ | Appium or device screenshots |
sources/ | Appium page source XML |
logs/ | device or simulator logs |
evidence/ | combined verification artifacts |
flow/ | source-flow analysis, checkpoint memory, replay records |
loop/ | JSONL iteration records |
reports/ | Markdown final reports |
ci/ | CI manifests, summaries, annotations |
security/ | source scans, generated plans, comparisons |
code.read_filecode.search_codecode.apply_patchcode.git_diffcode.create_branchcode.commit_changescode.open_prenv.preflightenv.compatibility_matrixenv.ensure_appiumbuild.detect_projectbuild.install_dependenciesbuild.run_lintbuild.run_unit_testsbuild.build_debug_apkbuild.build_release_candidatebuild.collect_build_logssecurity.scan_sourcesecurity.generate_test_plansecurity.compare_scanssecurity.release_gatedevice.list_devicesdevice.start_emulatordevice.stop_emulatordevice.install_appdevice.uninstall_appdevice.clear_app_datadevice.grant_permissionsdevice.capture_screenshotdevice.pull_logsios.list_simulatorsios.boot_simulatorios.shutdown_simulatorios.build_appios.install_appios.launch_appios.capture_screenshotios.collect_logsappium.create_sessionappium.delete_sessionappium.observe_screenappium.get_page_sourceappium.get_accessibility_treeappium.tap_by_textappium.tap_by_accessibility_idappium.tap_by_resource_idappium.tap_coordinatesappium.type_textappium.swipeappium.go_backappium.wait_for_visibleappium.assert_visibleappium.assert_not_visibleverify.assert_screen_contains_textverify.assert_no_crash_in_logcatverify.assert_appium_session_healthyverify.assert_api_responseverify.collect_evidenceverify.assert_navigation_reachedverify.assert_accessibility_labelsverify.assert_screenshot_diffverify.assert_sqlite_queryverify.hash_artifactflow.analyze_from_codeflow.generate_test_scenariosflow.run_scriptflow.record_checkpointflow.record_test_runflow.plan_replayflow.replay_to_checkpointflow.read_memoryflow.clear_memoryloop.record_iterationloop.read_iterationsloop.generate_reportci.collect_artifact_manifestci.write_github_step_summaryci.comment_prci.create_github_annotationspolicy.list_toolsorchestrator.run_android_validation_looporchestrator.run_ios_validation_loopenv.preflight says Appium is missingStart Appium and make sure APPIUM_SERVER_URL points to it:
env.preflight accepts either a reachable Appium server or a global appium command.
Start Appium with Android environment variables:
Prefer accessibility ids or resource ids. If using text, this server first tries a clickable parent containing the text, then falls back to the text node. For custom Flutter or React Native widgets, add stable semantics/accessibility ids when possible.
Use flow.plan_replay first. Raise minimumScore, record better checkpoints, and avoid checkpointing transient loading states.
Run Appium on the host and point the container to it with host.docker.internal. On Linux, add --add-host=host.docker.internal:host-gateway.
iOS simulator workflows require macOS with Xcode. Run iOS tools directly on the macOS host or a macOS self-hosted runner.
npm pack --dry-run fails with npm cache permissionsUse a clean cache:
The Dockerfile also runs the test suite during image build.
MIT. See LICENSE.