Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@devilge build, install, launch app and dump UI"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server that lets an AI assistant — typically Claude — develop, drive, and observe an Android / KMM app end-to-end.
devilge exposes 33 tools that cover the full inner loop: read the project, build it, install it, launch it, drive its UI, capture errors and network traffic, run tests. Anything an LLM coding agent would otherwise have to ask the user to do manually.
Category | Tools | Purpose |
Device read (8) |
| Observe device + project state |
Project static (3) |
| Inspect Gradle/KMM project + run any Gradle task |
Device drive (7) |
| Manipulate the running app |
Locators + waits (6) |
| Semantic UI navigation, no coordinate magic |
Lifecycle (5) |
| Cold-start app, run Espresso tests, fast install |
Maestro flows (optional) (3) |
| Reusable YAML flows for recurring navigation |
Composition (1) |
| Chain multiple devilge tools in one round trip |
215 unit tests in Vitest, all green. Strict TypeScript (strict, noUncheckedIndexedAccess).
Hosts that confirm every tool call (Claude Desktop, Cowork) can become noisy when the agent walks through multi-step UI flows. devilge_batch collapses a sequence into a single MCP call so the user approves once for the whole sequence.
// Tap "Settings", wait, screenshot, tap a row, screenshot — one approval.
{
"actions": [
{ "name": "devilge_tap_text", "input": { "text": "Settings" } },
{ "name": "devilge_wait_for_idle", "input": { "timeoutMs": 5000 } },
{ "name": "devilge_take_screenshot" },
{ "name": "devilge_tap_text", "input": { "text": "Wallpaper & style" } },
{ "name": "devilge_take_screenshot" }
]
}Rules: capped at 20 actions per call; cannot be nested; cannot include destructive tools (devilge_clear_app_data, devilge_install_apk) — those always require their own dedicated prompt; stops on the first error and reports which step failed.
All tools also expose MCP annotations (readOnlyHint, idempotentHint, destructiveHint, openWorldHint). Hosts that respect annotations can auto-approve safe reads and prompt only on state-changing tools.
Related MCP server: Specter MCP
Clean / hexagonal layering, every concern replaceable in isolation:
src/
├── config/ # Config loading, structured logger, typed errors
├── domain/
│ ├── entities/ # Pure data types
│ └── ports/ # Interfaces the application talks to
├── application/ # Use cases — orchestrate ports, no IO of their own
├── infrastructure/
│ ├── adb/ # AdbAdapter, AdbAppController, runners, parsers
│ ├── build/ # Gradle adapter + parsers (compile errors, JUnit, Lint)
│ ├── maestro/ # Optional Maestro adapter + YAML validator
│ ├── network/ # Ktor logcat parser + header sanitizer
│ ├── scanners/ # ComposePreviewScanner, ProjectScanner, FileWalker
│ └── security/ # PathValidator, CommandSanitizer
└── presentation/
└── tools/ # MCP tool definitions (Zod schemas + handlers)src/server.ts is the composition root: it constructs every concrete dependency and wires them into an McpServer. Nothing else in the codebase performs construction.
devilge runs on a developer's machine, exposes mutating tools to an LLM, and shells out to ADB and (optionally) Gradle / Maestro. It assumes the operator connects only to a dev emulator or wiped test device, never a personal device with logged-in apps.
Project sandbox. All filesystem reads/writes resolve, after symlink resolution, to paths inside DEVILGE_ANDROID_PROJECT_ROOT or the configured outputs / flows roots. Any escape throws SecurityError.
No shell. Every external process (adb, gradlew, maestro) is spawned with shell: false and an argv array. Arguments are never concatenated into strings.
Strict argument allowlists. Device serials, logcat tags, package names, activity names, deep links, Gradle tasks, Maestro flow names and env-var keys all pass through CommandSanitizer regex allowlists before reaching argv.
Resource caps. Logcat capped (5000 line ceiling), ADB stdout cap 8 MiB, Gradle output cap 256 KiB ring buffer, file scans bounded, screenshot timeout 15 s, instrumented-test timeout 30 min default cap.
Symlinks ignored. Walkers never follow symlinks.
Logs go to stderr only. Stdout is reserved for the MCP JSON-RPC transport.
Errors are sanitized. Only DevilgeError subclasses surface their messages. Unexpected exceptions become an opaque INTERNAL_ERROR.
Header redaction. Authorization, Cookie, Set-Cookie, X-API-Key and other well-known sensitive headers are redacted from get_network_calls output.
Maestro runScript: denied by default. YAML flows containing runScript: blocks (which execute JS) are rejected unless the operator explicitly sets DEVILGE_ALLOW_FLOW_SCRIPTS=true.
No frontmost-app check. devilge does NOT verify that the targeted package matches the device's foreground app. That check is a deployment concern — keep your dev device clean.
The MVP does include write tools (input automation, app install, data wipe, force-stop). These are gated to a dev-only device by operator policy, not by server logic.
cd devilge
npm install
cp .env.example .env
# edit .env with your project's absolute path
npm run buildRun the tests:
npm testVerify the build:
npm run typecheck # static type-check (no emit)
npm run build # emit dist/
npm run lint # eslintAdd an entry to your claude_desktop_config.json (path varies by OS):
{
"mcpServers": {
"devilge": {
"command": "node",
"args": ["/absolute/path/to/devilge/dist/index.js"],
"env": {
"DEVILGE_ANDROID_PROJECT_ROOT": "/absolute/path/to/your/android/project",
"DEVILGE_KTOR_LOG_TAG": "HttpClient"
}
}
}
}Restart Claude Desktop. The 33 tools should appear in the tool picker.
DEVILGE_ANDROID_PROJECT_ROOT=/absolute/path/to/your/android/project \
DEVILGE_KTOR_LOG_TAG=HttpClient \
npx --yes @modelcontextprotocol/inspector \
node dist/index.jsVariable | Required | Default | Description |
| ✅ | — | Absolute path to the Android/KMM project. All file reads are sandboxed under this directory. |
|
| Absolute path to the | |
| — | Default | |
|
| Default cap for | |
|
| One of | |
|
| Logcat tag the HTTP-client logger writes under. Use | |
|
| Which parser(s) to apply. | |
|
| Where screenshots / UI dumps land. Add to | |
|
| Where Maestro YAML flows live. | |
| auto-detected from PATH | Absolute path to the | |
|
| Set to |
Maestro is optional. Without it installed, every other devilge tool keeps working. The three flow tools (run_maestro_flow, list_maestro_flows, validate_maestro_flow) register unconditionally and return MAESTRO_NOT_INSTALLED when the binary isn't found.
To enable:
brew tap mobile-dev-inc/tap
brew install maestro
# or
curl -Ls "https://get.maestro.mobile.dev" | bashRestart the inspector. Flows go in <project>/devilge-flows/<name>.yaml. Example:
appId: com.example.your.app
---
- launchApp:
clearState: true
- tapOn: "Email"
- inputText: ${EMAIL}
- tapOn: "Password"
- inputText: ${PASSWORD}
- tapOn: "Sign in"
- assertVisible: "Home"Then:
{
"name": "login_flow",
"params": { "EMAIL": "user@example.com", "PASSWORD": "..." }
}MAESTRO_DISABLE_ANALYTICS=true is injected automatically. runScript: blocks are denied unless you opt in.
You can render @Preview Composables to PNG without launching the full app. devilge does NOT add a dedicated tool for this — the existing run_gradle_task plus the official Google plugin cover it cleanly, and adding a wrapper would make us depend on Gradle conventions that vary by project.
This is completely optional: if you don't add the plugin, devilge runs unchanged. You only lose this specific workflow.
To enable in your project, add to your Compose module's build.gradle.kts:
plugins {
// existing plugins...
id("com.android.compose.screenshot") version "0.0.1-alpha10"
}
android {
experimentalProperties["android.experimental.enableScreenshotTest"] = true
}And in gradle/libs.versions.toml:
[plugins]
composeScreenshot = { id = "com.android.compose.screenshot", version = "0.0.1-alpha10" }Once the plugin is in place, render previews from the LLM via the existing tool:
devilge_run_gradle_task {
"task": ":composeApp:validateDebugScreenshotTest"
}The PNGs land under composeApp/build/outputs/screenshotTest/.... Claude can then read them via its Read tool to verify visual output without installing the app.
1. run_gradle_task ":composeApp:assembleDebug" # build once at start
2. install_apk { "module": ":composeApp" } # ~5-8 s vs Gradle's 30-60 s
3. launch_app { "packageName": "...", "clean": true }
4. tap_text / set_text / wait_for_text # navigate to the screen
5. take_screenshot # confirm visual state
6. get_app_errors { "followMs": 10000 } # capture errors as they happen
7. get_network_calls # verify HTTP requests
8. on bug → edit code → back to step 1 (Gradle is incremental, fast)For recurring navigation paths (login, search, etc.), capture once as a Maestro flow and replay with one tool call.
Compose Live Edit MCP — true HMR for Android Compose. Major project (~2-3 months MVP, JVMTI agent + bytecode transformation + protocol). Waiting for JetBrains' Compose Hot Reload to land for Android first; the wrapper would be ~1-2 weeks.
pull_room_database — pull Room SQLite from device, expose readonly queries. Useful for inspecting cached state.
pull_anr_traces + deobfuscate_stacktrace — diagnose runtime hangs and ProGuard-mapped release crashes.
dumpsys_meminfo / dumpsys_gfxinfo / measure_cold_start — runtime performance metrics.
describe_compose_codebase — structural map of the project (data classes, XML resources, color literal frequencies, composables) so the LLM doesn't have to grep at session start. Considered, deferred until proven necessary in real use.
MIT
Executes a sequence of devilge tools sequentially in a single MCP call. Stops on the first error. Use this to chain predictable steps such as tap → wait_for_idle → take_screenshot, reducing tool-call overhead and permission prompts in the host UI.
Rules: • Capped at 20 actions per call. • Cannot call itself (no nesting). • Cannot include destructive tools (devilge_clear_app_data, devilge_install_apk). Invoke those directly so the user always sees a dedicated confirmation prompt. • Each sub-tool's input is validated before its handler runs.
Returns the concatenated content of every successful step, prefixed with a step label, plus a summary line. On failure, sets isError=true and reports which step stopped the batch and why.
Inputs: actions (required).
Runs pm clear <pkg> — wipes all app data including caches, databases, SharedPreferences, tokens. The app behaves like a fresh install on next launch. DESTRUCTIVE. Recommended only on dev emulators or wiped test devices, never on personal devices with logged-in apps.
Inputs: packageName (required), serial.
Captures the current foreground UI tree using uiautomator dump. Returns a structured tree of nodes (text, resourceId, contentDescription, bounds, clickable, etc.). Useful for finding elements by text/ID before tapping, or for reasoning about layout state.
Inputs: serial.
Runs am force-stop <pkg> — kills every process of the given app. Useful before relaunch to ensure a cold start, or when an app is hung.
Inputs: packageName (required), serial.
Returns recent error-level logs for a specific Android app, filtered by its package name (resolved to PID via adb shell pidof). Multi-line stack traces are coalesced into a single entry with message + stackTrace[]. Default minLevel is "E"; default exclusions filter common Android system noise (Choreographer, OpenGLRenderer, etc.). Returns empty if the app is not running.
Inputs: packageName (required), serial, followMs, minLevel, +2 more.
Returns the full source code of a @Preview composable, including its annotations and body.
Inputs: filePath (required), functionName (required).
Returns every Jetpack Compose @Preview in the project organized as modules → files → functions → variants. Multiple @Preview annotations on the same Composable are grouped as variants of one function. Includes a totals summary by group and an orphans bucket for previews outside any known module.
Inputs: maxFiles, moduleFilter.
Reads recent logcat output from a connected Android device or emulator using adb. Useful for diagnosing crashes, ANRs, runtime errors, and tracing application logs.
Inputs: serial, maxLines, minLevel, tagFilter.
Returns recent HTTP request/response pairs captured from the running Android app. Parses two formats from logcat: Ktor Logging plugin (tag "HttpClient" by default) and OkHttp HttpLoggingInterceptor (tag "OkHttp" by default — used by Retrofit). The format is auto-detected by content; configure via DEVILGE_HTTP_LOG_FORMAT if needed. Requires the app's HTTP logger to be active (Ktor LogLevel.HEADERS+ / OkHttp Level.HEADERS+; BODY/ALL recommended to capture bodies). Sensitive headers (Authorization, Cookie, Set-Cookie, X-API-Key, etc.) are redacted automatically.
Inputs: tag, serial, maxCalls, logcatLines, +3 more.
Returns a high-level snapshot of the configured Android/KMM Gradle project: modules, types (android-app / kmm-shared / library), source sets, and key versions.
Inputs: no named parameters.
Sends a key event (adb shell input keyevent KEYCODE_<NAME>). Allowed keys: BACK, HOME, MENU, APP_SWITCH, POWER, ENTER, TAB, DEL, FORWARD_DEL, ESCAPE, DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT, DPAD_CENTER, VOLUME_UP, VOLUME_DOWN, VOLUME_MUTE, PAGE_UP, PAGE_DOWN, MOVE_HOME, MOVE_END, SEARCH.
Inputs: code (required), serial.
Sends a swipe gesture (adb shell input swipe) from (x1,y1) to (x2,y2) over durationMs (default 300). Useful for scrolling lists, dismissing overlays, performing simple gestures.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +2 more.
Sends a tap (adb shell input tap) at the given device pixel coordinates. Prefer the higher-level devilge_tap_text (Phase 13) when available — it is more resilient to layout changes than raw coordinates.
Inputs: x (required), y (required), serial.
Types the given text into whatever field currently has focus on the device (adb shell input text). Spaces are escaped to %s by adb. NUL bytes and newlines are rejected.
Inputs: text (required), serial.
Lists Android applicationIds installed on the device, optionally filtered by a substring. For each match, reports whether a process is currently running and its PID. Use this to discover the right packageName value before calling devilge_get_app_errors.
Inputs: query, serial, maxResults.
Installs an APK via adb install -r directly, bypassing Gradle. Much faster than run_gradle_task installDebug for the iterate-on-source-then-reinstall loop. Pass either apkPath (explicit file) or module (auto-locate <projectRoot>/<module>/build/outputs/apk/<variant>/*.apk). Recommended workflow: assemble once with run_gradle_task assembleDebug, then re-install with this tool on each iteration — saves the Gradle configuration overhead each time.
Inputs: module, serial, apkPath, variant.
Launches the app via am start -W. Returns cold-start metrics (waitTimeMs / totalTimeMs / thisTimeMs) when available. With clean=true, force-stops and wipes app data first. With deepLink, opens an arbitrary URI handled by the app. With activity, targets a specific component. Without either, devilge resolves the launcher activity automatically (falls back to monkey if resolution fails).
Inputs: packageName (required), clean, serial, activity, +1 more.
Statically scans the configured Android/KMM project for Jetpack Compose @Preview functions and returns their locations plus parsed annotation parameters.
Inputs: maxFiles, moduleFilter.
Lists every Android device or emulator currently visible to ADB on this machine.
Inputs: no named parameters.
Lists every *.yaml/*.yml flow file under DEVILGE_FLOWS_ROOT, returning name, relative path, size and a 5-line preview. Works WITHOUT Maestro installed — useful to see what reusable flows exist before deciding whether to invest in installing Maestro.
Inputs: no named parameters.
Increase the device-side logcat ring buffer so that recent HTTP / app logs are not evicted within seconds. Applies to subsequent captures only — entries already lost are gone. Recommended whenever Ktor LogLevel.ALL produces dozens of lines per request.
Inputs: sizeMb (required), serial.
Runs a Gradle task in the configured Android/KMM project (via the project's gradlew wrapper) and returns a structured summary: success flag, parsed compile errors (kotlinc/javac/kapt/ksp), JUnit test results from build/test-results, Android Lint findings, "What went wrong" failure blocks, plus the tail of stdout/stderr.
Inputs: task (required), extraArgs, tailBytes, timeoutMs.
Runs :<module>:connectedDebugAndroidTest against an attached device, optionally filtered to a single class or class#method. Returns the same structured result as devilge_run_gradle_task (success, JUnit-parsed testResults, compile errors, build failures, raw output tail). Reuses the existing JUnitXmlParser to read androidTest results.
Inputs: module, tailBytes, testClass, timeoutMs, +1 more.
Executes a Maestro YAML flow from DEVILGE_FLOWS_ROOT (default: /devilge-flows/). Maestro is OPTIONAL — if not installed, this tool returns MAESTRO_NOT_INSTALLED with the install command (brew install maestro). When installed, runs maestro test <flow> with optional params injected as -e KEY=VALUE. runScript: blocks in the YAML are denied by default; set DEVILGE_ALLOW_FLOW_SCRIPTS=true to allow. MAESTRO_DISABLE_ANALYTICS is always injected.
Inputs: name (required), params.
Toggles the device-side developer options "Show touches" and "Pointer location". When enabled, every tap/swipe leaves a visible marker on screen and the live coords appear in a debug strip — useful to confirm input_tap/input_swipe are landing where expected. Persists until the device reboots. Recommended: enable once at start of a driving session, disable when done.
Inputs: enabled (required), serial.
Locates the input field associated with a label, taps to focus it, and types the given value. Heuristic: focused EditText → contentDescription match → text match → EditText after a label TextView. Returns the matched field summary.
Inputs: label (required), value (required), serial.
Captures the current device screen (adb exec-out screencap -p) and saves a PNG under the configured outputs directory. Returns the absolute path so the LLM client can read the image. Default outputs root: <projectRoot>/.devilge-outputs/screenshots/.
Inputs: serial.
Like devilge_tap_text but matches by resource-id. More stable across copy/locale changes than text matching when the project uses Modifier.testTag.
Inputs: id (required), serial.
Internally dumps the UI, finds the unique node whose text or contentDescription matches, and taps its bounds center. Errors when 0 or >1 matches — the caller must disambiguate with a more specific text or use contains for substring match.
Inputs: text (required), serial, contains.
Statically validates a flow YAML: requires appId:, --- separator, at least one step, and flags runScript: blocks (denied unless DEVILGE_ALLOW_FLOW_SCRIPTS=true). Does NOT execute Maestro — works without the binary installed. Use this before run_maestro_flow to surface syntactic problems quickly.
Inputs: name (required).
Polls the UI dump and returns when N consecutive dumps have an identical structural digest, or the timeout elapses. Useful between a tap and the next action to absorb animations / asynchronous updates without sleeps.
Inputs: serial, timeoutMs, stableSamples.
Polls the UI dump until a node with the given resource-id appears, or timeout.
Inputs: id (required), serial, timeoutMs.
Polls the UI dump until a node whose text or contentDescription matches appears, or the timeout elapses. Returns {matched, attempts, elapsedMs, matchedNode?}. Never throws — the caller branches on matched.
Inputs: text (required), serial, contains, timeoutMs.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 33 tools
Each tool has a distinct purpose with clear names and descriptions. Overlaps like multiple tap tools are differentiated by matching strategy (text, resource-id, coordinates). Logging, preview, and UI tools are also well separated.
All tools follow the 'devilge_verb_noun' pattern using snake_case. The naming is uniform and predictable, making it easy to infer tool functionality from the name alone.
33 tools is above the typical well-scoped range, but the tool surface covers a broad domain (device interaction, UI automation, app lifecycle, Gradle, Maestro, batch operations). The count feels justified given the comprehensiveness, though some consolidation might be possible.
The tool set covers the full spectrum of Android development/testing automation: device discovery, logging, UI interaction, app management, preview inspection, build tasks, network monitoring, and Maestro integration. No major gaps are apparent for the stated purpose.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Disposable cloud Android emulators for coding agents: run an APK or PR build, tap, type, screenshot.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
