# Mobiloop Mcp

> Guarded MCP servers for agentic mobile build-test-fix loops with Appium, device automation, verification, and flow memory.

- **Type:** MCP server
- **Install:** `agentstack add mcp-enessubass-mobiloop-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [enessubass](https://agentstack.voostack.com/s/enessubass)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [enessubass](https://github.com/enessubass)
- **Source:** https://github.com/enessubass/mobiloop-mcp

## Install

```sh
agentstack add mcp-enessubass-mobiloop-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MobiLoop MCP

Guarded MCP servers for agentic mobile development loops.

```text
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**: optionally block high-impact tools unless input includes a valid approval payload.
- **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:

```text
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
  |
  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.

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

```bash
appium --address 127.0.0.1 --port 4723
```

Local Appium installs also work:

```bash
npx appium --address 127.0.0.1 --port 4723
```

For Android, make sure the Appium process can see:

```bash
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"
```

## Install From Source

```bash
npm ci
npm test
```

Run the all-in-one MCP server:

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

For development:

```bash
npm run dev
```

## CLI Fallback

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

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

Inspect tool policy metadata:

```bash
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:

```bash
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:

```bash
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.

```json
{
  "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.

```json
{
  "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.

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

## Configuration

Copy the example if you want file-based config:

```bash
cp mobiloop.config.example.json mobiloop.config.json
```

Or point to it explicitly:

```bash
export MOBILOOP_CONFIG=/absolute/path/to/mobiloop.config.json
```

`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                                                               |
| ---------------------- | ------------------------------- | --------------------------------------------------------------------- |
| `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/` |
| `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`         | Appium server endpoint                                                |
| `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                                     |
| `forbiddenPathGlobs`   | secret-like defaults            | Files blocked from read/write operations                              |
| `toolPolicies`         | built-in defaults               | Per-tool risk and approval metadata overrides                         |
| `requireApproval`      | `false`                         | Require approval payloads for high-impact tools                       |
| `redactArtifacts`      | `true`                          | Redact common secrets and PII from text artifacts and text responses  |

Environment variables override selected fields:

```bash
export MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app
export APPIUM_SERVER_URL=http://127.0.0.1:4723
export MOBILOOP_RUN_ID=local-login-smoke
export MOBILOOP_REQUIRE_APPROVAL=true
```

The config schema is available at [schema/mobiloop.config.schema.json](schema/mobiloop.config.schema.json). See [docs/CONFIGURATION.md](docs/CONFIGURATION.md).

Approval payloads use this shape:

```json
{
  "approval": {
    "approved": true,
    "approvedBy": "human-or-ci",
    "reason": "Run Android validation on emulator",
    "expiresAt": "2026-05-11T12:00:00Z"
  }
}
```

## Recommended First Run

1. Start an emulator or connect a device.
2. Start Appium.
3. Point `MOBILOOP_WORKSPACE_ROOT` at your mobile app.
4. Run `env.preflight`.
5. Run `flow.analyze_from_code`.
6. Run build/lint/unit tests.
7. Install the app on the device.
8. Create an Appium session.
9. Drive and verify one small user flow.
10. Collect evidence and generate a report.

For a Flutter Android app, the rough tool sequence is:

```text
env.preflight { "target": "flutter" }
flow.analyze_from_code
build.detect_project
build.install_dependencies
build.run_lint
build.run_unit_tests
build.build_debug_apk
device.list_devices
device.install_app
appium.create_session
appium.wait_for_visible
appium.tap_by_text
verify.assert_no_crash_in_logcat
verify.collect_evidence
loop.record_iteration
loop.generate_report
```

## Android Orchestrator

`orchestrator.run_android_validation_loop` runs a bounded Android loop across build, install, Appium, verification, evidence, and iteration records.

Minimal shape:

```json
{
  "goal": "Build and verify login flow on Android.",
  "kind": "flutter",
  "packageName": "com.example.app",
  "serial": "emulator-5554",
  "runLint": true,
  "runUnitTests": true,
  "buildDebugApk": true,
  "clearAppData": true,
  "collectEvidence": true,
  "maxTestIterations": 3,
  "appiumCapabilities": {
    "platformName": "Android",
    "appium:automationName": "UiAutomator2",

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [enessubass](https://github.com/enessubass)
- **Source:** [enessubass/mobiloop-mcp](https://github.com/enessubass/mobiloop-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-enessubass-mobiloop-mcp
- Seller: https://agentstack.voostack.com/s/enessubass
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.