kahlo-mcp

# (Frida) Kahlo MCP <p> <img src="kahlo-01.png" align="left" width="200" hspace="12" vspace="6" alt="Kahlo logo" /> <b>Kahlo</b> is a <a href="https://frida.re/">Frida</a> MCP server that exposes Android dynamic instrumentation capabilities to AI agents. It wraps Frida's runtime manipulation APIs into a structured tool interface, enabling AI systems to attach to processes, inject instrumentation code, capture telemetry, and iterate on analysis workflows without manual intervention. <br><br> The server manages the full lifecycle of instrumentation sessions: device discovery, process attachment or spawning, job execution with per-script isolation, event streaming with cursor-based pagination, and binary artifact storage. Jobs run in isolated Frida scripts with automatic cleanup on cancellation. A built-in stdlib provides many standard code primitives for Java object inspection, stack traces, Intent parsing, and method hooking. <br><br> </p> For more details, please read the accompanying blog post: [https://knifecoat.com/Posts/Scalable+research+tooling+for+agent+systems](https://knifecoat.com/Posts/Scalable+research+tooling+for+agent+systems) <p clear="left" align="center"> <br><img src="kahlo-02.svg" alt="Kahlo Architecture Diagram" width="800" /> </p> ## Setup & Installation Edit the existing [`kahlo-mcp/config.json`](kahlo-mcp/config.json) in this repo and set `adbPath` to the **full path** of the ADB binary you want to use. This works fine on Windows and UNIX systems. ```json { "transport": "stdio", "logLevel": "info", "dataDir": "./data", "adbPath": "/path/to/adb" } ``` Install dependencies and build: ```bash cd kahlo-mcp npm install npm run build ``` | Field | Required | Description | |-------|----------|-------------| | `transport` | Yes | Only `"stdio"` is supported for now (SSE coming) | | `logLevel` | Yes | Use `"info"` for now (more controls coming) | | `dataDir` | Yes | Directory for runs, modules, drafts, artifacts. Defaults to `kahlo-mcp/data` | | `adbPath` | Yes | Full path to ADB binary | Upload a `frida-server` binary to your device that matches the `frida` version in [`kahlo-mcp/package.json`](kahlo-mcp/package.json), then run it (ideally as root). ## MCP Integration ### Claude Code Edit your claude user json preference file (`/mcp` will show you where): ```json { "mcpServers": { "frida-kahlo": { "type": "stdio", "command": "node", "args": [ "C:/Your/Full/Path/k4hlo/kahlo-mcp/dist/index.js" ], "cwd": "C:/Your/Full/Path/k4hlo/kahlo-mcp" } } } ``` ### Cursor Add to Cursor MCP settings (Preferences > Cursor Settings > Tools & MCP): ```json { "mcpServers": { "frida-kahlo": { "command": "node", "args": ["/Your/Full/Path/k4hlo/kahlo-mcp/dist/index.js"], "cwd": "/Your/Full/Path/k4hlo/kahlo-mcp" } } } ``` ### Codex CLI You will find your `toml` file under your user configuration folder for `.codex`: ```toml model = "gpt-5.3-codex" model_reasoning_effort = "medium" [mcp_servers.frida-kahlo] command = "node" args = ["/Your/Full/Path/k4hlo/kahlo-mcp/dist/index.js"] cwd = "/Your/Full/Path/k4hlo/kahlo-mcp" ``` ## MCP Tools Reference This section is a quick, utilitarian map of the tool surface. For the complete operational contract (concepts, workflows, failure modes, and full stdlib reference), ask you AI to call `kahlo_mcp_about` to tell you more! ### Introspection - `kahlo_mcp_about`: returns the kahlo operational contract (tool inventory, concepts, workflows, failure modes, stdlib reference). ### Devices, processes, and ADB - `kahlo_devices_list`: list connected devices ready for instrumentation. - `kahlo_devices_get` (`device_id`): detailed device info (model/version/transport) and readiness signals. - `kahlo_devices_health` (`device_id`): health check for ADB + frida-server presence/running. - `kahlo_processes_list` (`device_id`, `scope?`): list running processes (pid + name). Use this before `mode="attach"` to get the exact process name. - `kahlo_adb_command` (`command[]`, `device_id?`, `timeout_ms?`): run an ADB command with the configured ADB binary. For root-only paths, wrap with `su -c` (e.g., `['shell','su','-c','ls /data/data/<pkg>']`). ### Targets (attach/spawn + lifecycle) - `kahlo_targets_ensure`: - **Purpose**: create/ensure a target (an instrumented app process hosting the in-process orchestrator). - **Params**: `device_id`, `package`, `mode` (`attach|spawn`), `gating?` (`none|spawn|child`), `bootstrap?`, `bootstrap_params?`, `bootstrap_type?`, plus optional `child_*` bootstrap fields. - **Notes**: - `mode="attach"`: `package` is the *process name* from `kahlo_processes_list` (often not the Android package id). - `mode="spawn"`: `package` is the Android package id (e.g., `com.example.app`). - `gating="spawn"` requires `bootstrap` (early hooks while app is suspended, then it resumes automatically). - `gating="child"` is present but **does not work on Android** (zygote forks child processes). For multi-process apps, discover `com.example.app:process` names and attach separately. - `kahlo_targets_status` (`target_id`): target lifecycle + orchestrator agent state (use to diagnose crashes/reinjecting). - `kahlo_targets_detach` (`target_id`): detach cleanly; cancels all jobs for that target. ### Jobs (run instrumentation code) - `kahlo_jobs_start`: - **Purpose**: start an isolated job (one Frida script instance) inside a target. - **Params**: `target_id`, `type?` (`oneshot|interactive|daemon`), `ttl?`, `params?`, and `module`: - `{ kind: 'module_ref', module_ref: 'name@version' }` - `{ kind: 'draft_id', draft_id: '...' }` - `{ kind: 'source', source: '...' }` (inline JS for fast iteration) - **Notes**: daemon jobs should call `ctx.heartbeat()` periodically; cancellation unloads the script and Frida cleans up hooks/timers/state. - `kahlo_jobs_status` (`job_id`): job lifecycle + heartbeat health + metrics + error/result. - `kahlo_jobs_list` (`target_id`): list jobs for a target (active + historical). - `kahlo_jobs_cancel` (`job_id`): cancel a job; unloads its script (best-effort cleanup via Frida). ### Telemetry and snapshots - `kahlo_events_fetch` (`target_id?` or `job_id?`, `cursor?`, `limit?`, `filters?`): poll structured events with cursor-based pagination. `filters` supports `kind` and/or `level`. - `kahlo_snapshots_get` (`target_id`, `kind`, `options?`): point-in-time state queries (use sparingly; can be expensive). ### Artifacts (large outputs) - `kahlo_artifacts_list` (`target_id?` or `job_id?`): list artifacts produced by jobs (files/dumps/traces/etc). - `kahlo_artifacts_get` (`artifact_id`): fetch artifact metadata and either inline payload (small) or a storage reference (large). ### Modules and drafts (reusable job code) - `kahlo_modules_list`: list versioned modules in the module store. - `kahlo_modules_get` (`module_ref` like `name@1.2.3`): fetch module source + manifest + provenance. - `kahlo_modules_createDraft` (`source`, `name?`, `manifest?`): create a mutable draft for iteration. - `kahlo_modules_createDraftFromJob` (`job_id`, `name?`): "save my working job" as a draft. - `kahlo_modules_listDrafts`: list drafts (metadata only). - `kahlo_modules_getDraft` (`draft_id`): fetch draft metadata + full source. - `kahlo_modules_updateDraft` (`draft_id`, `source`): replace draft source (iterate quickly). - `kahlo_modules_promoteDraft` (`draft_id`, `name`, `version_strategy`, `notes?`): freeze a draft into a versioned module (`patch|minor|major`). - `kahlo_modules_promoteFromJob` (`job_id`, `name`, `version_strategy`, `notes?`): promote a tested job directly into a versioned module. ## Stdlib (`ctx.stdlib`) Every job script gets a preloaded standard library under `ctx.stdlib`. This is the preferred way to do common "instrumentation chores" (stack capture, safe Java calls, overload-safe hooks, bytes/strings, Intent parsing, etc.) without rewriting boilerplate. Source of truth: `kahlo-mcp/src/backend/jobs/jobScriptStdlib.js`. ### Top-level helpers - `ctx.stdlib.isJavaAvailable()`: returns `true` if Java APIs can be used in this process. - `ctx.stdlib.getJavaBridge()`: returns the Java bridge handle (or `null`). - `ctx.stdlib.requireJava(operation?)`: returns the Java bridge or throws with a helpful message. ### `stack` - Java stack traces - `capture({ skip?, limit? })`: capture frames as objects (`className`, `methodName`, `fileName`, `lineNumber`, `isNative`). - `toString({ skip?, limit?, separator? })`: formatted stack trace string. - `filter(frames, pattern)`: keep frames matching a prefix string or RegExp. - `findFirst(frames, pattern)`: first matching frame (or `null`). - `getCaller()`: best-effort "caller" frame (skips internal/runtime frames). - `getException(throwable)`: format a Java `Throwable` (message + stack + causes) as a string. ### `inspect` - Java object introspection - `className(obj)`, `simpleClassName(obj)` - `fields(obj, { includeInherited?, includeStatic? }?)`: enumerate fields (including private). - `methods(obj, { includeInherited?, includeStatic? }?)`: enumerate methods. - `getField(obj, fieldName)`: safe field read (`{ ok, value, error? }`). - `toJson(obj, { maxDepth?, maxArrayLength?, maxStringLength? }?)`: convert common Java objects to JSON-safe structures. - `isInstance(obj, className)` - `superclassChain(obj)` - `interfaces(obj, includeInherited?)` ### `classes` - discovery and loading - `find(pattern, { limit? }?)`: search loaded classes by prefix string or RegExp. - `enumerate(callbackOrOptions?)`: list loaded classes (either returns an array, or streams via callback depending on usage). - `load(className)`: safe `Java.use` (returns `null` on failure). - `isLoaded(className)`: quick check if a class is loaded. - `instances(className, { limit? }?)`: enumerate live heap instances (best-effort, can be expensive). - `getClassLoader(className)`: get the `ClassLoader` for a loaded class (or `null`). ### `bytes` - binary helpers - `toHex(data, { uppercase?, separator? }?)`, `fromHex(hex)` - `toBase64(data)`, `fromBase64(base64)` - `fromJavaBytes(byteArray)`, `toJavaBytes(uint8Array)` - `equals(a, b)`, `concat(...arrays)`, `slice(data, start, end?)` ### `strings` - conversions and encoding - `fromJava(javaStringLike)`, `toJava(jsString)` - `truncate(str, maxLength, ellipsis?)` - `fromUtf8(data)`, `toUtf8(str)` - `matches(str, pattern)` - `safeToString(obj, maxLength?)` ### `intent` - Intent parsing and construction - `parse(intent)`: returns a structured summary (action/data/type/categories/component/flags/extras). - `getExtras(intent)`: extract extras Bundle into a JS object (recurses on nested Bundles). - `getComponent(intent)`, `isExplicit(intent)` - `create({ action?, data?, type?, flags?, packageName?, className?, extras? })`: build a new Intent (returns `null` on failure). - `flagsToStrings(flags)`: decode the bitmask to flag names. ### `hook` - hook helpers (Java + native) - `method(className, methodName, { onEnter?, onLeave? })`: hook a method (all overloads if present). - `methodWithSignature(className, methodName, paramTypes[], { onEnter?, onLeave? })`: hook a specific overload. - `allOverloads(className, methodName, handler)`: hook all overloads with a single handler. - `constructor(className, handler)`: hook all `$init` overloads. - `onClassLoad(className, callback)`: run `callback(Java.use(className))` once the class becomes available. - `native(addressOrSymbol, callbacks)`: `Interceptor.attach` wrapper for native hooks. - `replace(classWrapper, methodName, replacement)`: replace implementation and get a restore function. ### `safe` - fail-closed wrappers - `java(fn)`: run in `Java.performNow` and return `{ ok, result?, error? }`. - `call(fn)`: try/catch wrapper returning `{ ok, result?, error? }`. - `timeout(fn, timeoutMs)`: Promise wrapper returning `{ ok, result?, error? }` (does not cancel underlying work). - `tryUse(className)`: safe `Java.use` (returns `null` instead of throwing). - `invoke(obj, methodName, ...args)`: safe method invocation (returns `null` on any failure). - `get(obj, keyPath, defaultValue?)`: safe property lookup (supports dot paths). ### `time` - timestamps and rate limiting - `now()`, `nowMs()`, `hrNow()` - `format(ms)`, `stopwatch()` - `sleep(ms)`, `measure(fn)` - `debounce(fn, delayMs)`, `throttle(fn, intervalMs)`