MobiLoop MCP

Guarded MCP servers for agentic mobile build-test-fix loops.

Documentation site | Security model | Tool reference

code change -> build -> install on device -> Appium test -> evidence -> classify -> report

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.

Highlights

• Evidence-first mobile loops: build logs, screenshots, Appium XML source, logcat/simulator logs, API responses, screenshot diffs, and iteration records.
• Android and iOS tool split: Android adb/emulator tools and iOS xcrun simctl/xcodebuild tools are separated.
• Appium UI automation: semantic taps, typing, swipes, back navigation, visibility assertions, screenshots, and accessibility summaries.
• Flow memory: record runtime screen checkpoints, remember the latest passing path, and auto-replay stable setup steps to a target checkpoint.
• Scenario generation and flow DSL: scan source for candidate E2E scenarios, then run high-level JSON flows with wait/tap/type/assert/evidence steps.
• Source-flow analysis: scan Flutter, React Native, Android, and iOS source for screen, route, transition, and visible-text candidates.
• Root-cause classification: classify logcat evidence into app bugs, automation errors, missing environment, remote rules, and test-data issues.
• Server-side approval gate: secure mode requires valid approval payloads for high-impact tools.
• Built-in mobile security loop: scan source and platform settings, generate a test plan, compare fixes, and gate release decisions without another scanner package.
• Redaction by default: redact common secrets, bearer tokens, API keys, emails, and phone numbers from text artifacts, command output, and MCP/CLI text responses.
• Guarded code tools: workspace-only reads/searches/patches, forbidden secret paths, guarded branches, commits, and PR creation.
• Docker-ready MCP runtime: package the Node MCP server in Docker while keeping mobile SDKs, emulators, devices, and Appium on the host or runner.
• Composable binaries: run everything as one server or split each responsibility into its own MCP server.

What This Is

This project provides MCP tools for this architecture:

AI / MCP client
  |
  v
MobiLoop MCP
  |
  |-- code tools
  |-- environment preflight
  |-- build tools
  |-- Android device tools
  |-- iOS simulator tools
  |-- Appium tools
  |-- verification tools
  |-- flow-memory replay tools
  |-- loop/report tools
  |-- CI publication tools
  |-- Android/iOS orchestrators
  |-- security scan and release gate tools
  |
  v
mobile repo + emulator/device + Appium + build toolchain

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.

What This Is Not

• It is not a replacement for Android SDK, Xcode, Flutter, Gradle, React Native, Appium, or platform drivers.
• It is not a universal mobile emulator container. iOS simulator requires macOS, and Android emulator portability depends on host acceleration and device access.
• It is not an unrestricted shell bridge. Tools are structured and guarded.
• It is not a production deployer. Release signing, store upload, and production secrets remain outside the default scope.

Requirements

Install only what your target app needs.

Start Appium before Appium or flow replay tools:

appium --address 127.0.0.1 --port 4723

Local Appium installs also work:

npx appium --address 127.0.0.1 --port 4723

For Android, make sure the Appium process can see:

export ANDROID_HOME=/absolute/path/to/android/sdk
export ANDROID_SDK_ROOT=/absolute/path/to/android/sdk
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"

For an already-running Genymotion device, add its Android SDK platform tools to PATH, then verify the device before starting a flow:

export PATH="$HOME/Library/Android/sdk/platform-tools:$PATH"
adb devices -l

Install From Source

npm ci
npm test

Run the all-in-one MCP server:

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/index.js

For development:

npm run dev

CLI Fallback

When an MCP client cannot expose the server as callable tools, use the CLI wrapper:

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/cli.js list-tools

Inspect tool policy metadata:

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/cli.js list-tools --json

The same metadata is available inside MCP through policy.list_tools.

Call any tool directly:

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/cli.js call flow.generate_test_scenarios '{"goal":"login smoke and validation"}'

Generate scenario candidates:

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/cli.js generate-scenarios "cover onboarding, login, and validation"

MCP Client Configuration

All-In-One Server

Use this for local development and simpler MCP clients.

{
  "mcpServers": {
    "mobiloop": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/index.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app",
        "APPIUM_SERVER_URL": "http://127.0.0.1:4723"
      }
    }
  }
}

Split Servers

Use split servers when you want tighter policy boundaries per responsibility.

{
  "mcpServers": {
    "mobile-code": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/code.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    },
    "mobile-build": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/build.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    },
    "mobile-device": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/device.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    },
    "mobile-appium": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/appium.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app",
        "APPIUM_SERVER_URL": "http://127.0.0.1:4723"
      }
    },
    "mobile-flow": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/flow.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app",
        "APPIUM_SERVER_URL": "http://127.0.0.1:4723"
      }
    },
    "mobile-verify": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/verify.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    },
    "mobile-loop": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/loop.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    }
  }
}

All binaries are listed below.