Skip to content
Back to search

kahlo-mcp

A Frida MCP server to enable autonomous AI assistance for Android instrumentation

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fuzzysecurity--kahlo-mcp/badge.svg)](/listings/fuzzysecurity--kahlo-mcp)

HTML

<a href="/listings/fuzzysecurity--kahlo-mcp"><img src="/api/listings/fuzzysecurity--kahlo-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

{
  "transport": "stdio",
  "logLevel": "info",
  "dataDir": "./data",
  "adbPath": "/path/to/adb"
}

Install dependencies and build:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 251 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # (Frida) Kahlo MCP
  2. <p>
  3. <img src="kahlo-01.png" align="left" width="200" hspace="12" vspace="6" alt="Kahlo logo" />
  4. <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.
  5. <br><br>
  6. 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.
  7. <br><br>
  8. </p>
  9. For more details, please read the accompanying blog post:
  10. [https://knifecoat.com/Posts/Scalable+research+tooling+for+agent+systems](https://knifecoat.com/Posts/Scalable+research+tooling+for+agent+systems)
  11. <p clear="left" align="center">
  12. <br><img src="kahlo-02.svg" alt="Kahlo Architecture Diagram" width="800" />
  13. </p>
  14. ## Setup & Installation
  15. 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.
  16. ```json
  17. {
  18. "transport": "stdio",
  19. "logLevel": "info",
  20. "dataDir": "./data",
  21. "adbPath": "/path/to/adb"
  22. }
  23. ```
  24. Install dependencies and build:
  25. ```bash
  26. cd kahlo-mcp
  27. npm install
  28. npm run build
  29. ```
  30. | Field | Required | Description |
  31. |-------|----------|-------------|
  32. | `transport` | Yes | Only `"stdio"` is supported for now (SSE coming) |
  33. | `logLevel` | Yes | Use `"info"` for now (more controls coming) |
  34. | `dataDir` | Yes | Directory for runs, modules, drafts, artifacts. Defaults to `kahlo-mcp/data` |
  35. | `adbPath` | Yes | Full path to ADB binary |
  36. 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).
  37. ## MCP Integration
  38. ### Claude Code
  39. Edit your claude user json preference file (`/mcp` will show you where):
  40. ```json
  41. {
  42. "mcpServers": {
  43. "frida-kahlo": {
  44. "type": "stdio",
  45. "command": "node",
  46. "args": [
  47. "C:/Your/Full/Path/k4hlo/kahlo-mcp/dist/index.js"
  48. ],
  49. "cwd": "C:/Your/Full/Path/k4hlo/kahlo-mcp"
  50. }
  51. }
  52. }
  53. ```
  54. ### Cursor
  55. Add to Cursor MCP settings (Preferences > Cursor Settings > Tools & MCP):
  56. ```json
  57. {
  58. "mcpServers": {
  59. "frida-kahlo": {
  60. "command": "node",
  61. "args": ["/Your/Full/Path/k4hlo/kahlo-mcp/dist/index.js"],
  62. "cwd": "/Your/Full/Path/k4hlo/kahlo-mcp"
  63. }
  64. }
  65. }
  66. ```
  67. ### Codex CLI
  68. You will find your `toml` file under your user configuration folder for `.codex`:
  69. ```toml
  70. model = "gpt-5.3-codex"
  71. model_reasoning_effort = "medium"
  72. [mcp_servers.frida-kahlo]
  73. command = "node"
  74. args = ["/Your/Full/Path/k4hlo/kahlo-mcp/dist/index.js"]
  75. cwd = "/Your/Full/Path/k4hlo/kahlo-mcp"
  76. ```
  77. ## MCP Tools Reference
  78. 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!
  79. ### Introspection
  80. - `kahlo_mcp_about`: returns the kahlo operational contract (tool inventory, concepts, workflows, failure modes, stdlib reference).
  81. ### Devices, processes, and ADB
  82. - `kahlo_devices_list`: list connected devices ready for instrumentation.
  83. - `kahlo_devices_get` (`device_id`): detailed device info (model/version/transport) and readiness signals.
  84. - `kahlo_devices_health` (`device_id`): health check for ADB + frida-server presence/running.
  85. - `kahlo_processes_list` (`device_id`, `scope?`): list running processes (pid + name). Use this before `mode="attach"` to get the exact process name.
  86. - `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>']`).
  87. ### Targets (attach/spawn + lifecycle)
  88. - `kahlo_targets_ensure`:
  89. - **Purpose**: create/ensure a target (an instrumented app process hosting the in-process orchestrator).
  90. - **Params**: `device_id`, `package`, `mode` (`attach|spawn`), `gating?` (`none|spawn|child`), `bootstrap?`, `bootstrap_params?`, `bootstrap_type?`, plus optional `child_*` bootstrap fields.
  91. - **Notes**:
  92. - `mode="attach"`: `package` is the *process name* from `kahlo_processes_list` (often not the Android package id).
  93. - `mode="spawn"`: `package` is the Android package id (e.g., `com.example.app`).
  94. - `gating="spawn"` requires `bootstrap` (early hooks while app is suspended, then it resumes automatically).
  95. - `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.
  96. - `kahlo_targets_status` (`target_id`): target lifecycle + orchestrator agent state (use to diagnose crashes/reinjecting).
  97. - `kahlo_targets_detach` (`target_id`): detach cleanly; cancels all jobs for that target.
  98. ### Jobs (run instrumentation code)
  99. - `kahlo_jobs_start`:
  100. - **Purpose**: start an isolated job (one Frida script instance) inside a target.
  101. - **Params**: `target_id`, `type?` (`oneshot|interactive|daemon`), `ttl?`, `params?`, and `module`:
  102. - `{ kind: 'module_ref', module_ref: 'name@version' }`
  103. - `{ kind: 'draft_id', draft_id: '...' }`
  104. - `{ kind: 'source', source: '...' }` (inline JS for fast iteration)
  105. - **Notes**: daemon jobs should call `ctx.heartbeat()` periodically; cancellation unloads the script and Frida cleans up hooks/timers/state.
  106. - `kahlo_jobs_status` (`job_id`): job lifecycle + heartbeat health + metrics + error/result.
  107. - `kahlo_jobs_list` (`target_id`): list jobs for a target (active + historical).
  108. - `kahlo_jobs_cancel` (`job_id`): cancel a job; unloads its script (best-effort cleanup via Frida).
  109. ### Telemetry and snapshots
  110. - `kahlo_events_fetch` (`target_id?` or `job_id?`, `cursor?`, `limit?`, `filters?`): poll structured events with cursor-based pagination. `filters` supports `kind` and/or `level`.
  111. - `kahlo_snapshots_get` (`target_id`, `kind`, `options?`): point-in-time state queries (use sparingly; can be expensive).
  112. ### Artifacts (large outputs)
  113. - `kahlo_artifacts_list` (`target_id?` or `job_id?`): list artifacts produced by jobs (files/dumps/traces/etc).
  114. - `kahlo_artifacts_get` (`artifact_id`): fetch artifact metadata and either inline payload (small) or a storage reference (large).
  115. ### Modules and drafts (reusable job code)
  116. - `kahlo_modules_list`: list versioned modules in the module store.
  117. - `kahlo_modules_get` (`module_ref` like `name@1.2.3`): fetch module source + manifest + provenance.
  118. - `kahlo_modules_createDraft` (`source`, `name?`, `manifest?`): create a mutable draft for iteration.
  119. - `kahlo_modules_createDraftFromJob` (`job_id`, `name?`): "save my working job" as a draft.
  120. - `kahlo_modules_listDrafts`: list drafts (metadata only).
  121. - `kahlo_modules_getDraft` (`draft_id`): fetch draft metadata + full source.
  122. - `kahlo_modules_updateDraft` (`draft_id`, `source`): replace draft source (iterate quickly).
  123. - `kahlo_modules_promoteDraft` (`draft_id`, `name`, `version_strategy`, `notes?`): freeze a draft into a versioned module (`patch|minor|major`).
  124. - `kahlo_modules_promoteFromJob` (`job_id`, `name`, `version_strategy`, `notes?`): promote a tested job directly into a versioned module.
  125. ## Stdlib (`ctx.stdlib`)
  126. 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.
  127. Source of truth: `kahlo-mcp/src/backend/jobs/jobScriptStdlib.js`.
  128. ### Top-level helpers
  129. - `ctx.stdlib.isJavaAvailable()`: returns `true` if Java APIs can be used in this process.
  130. - `ctx.stdlib.getJavaBridge()`: returns the Java bridge handle (or `null`).
  131. - `ctx.stdlib.requireJava(operation?)`: returns the Java bridge or throws with a helpful message.
  132. ### `stack` - Java stack traces
  133. - `capture({ skip?, limit? })`: capture frames as objects (`className`, `methodName`, `fileName`, `lineNumber`, `isNative`).
  134. - `toString({ skip?, limit?, separator? })`: formatted stack trace string.
  135. - `filter(frames, pattern)`: keep frames matching a prefix string or RegExp.
  136. - `findFirst(frames, pattern)`: first matching frame (or `null`).
  137. - `getCaller()`: best-effort "caller" frame (skips internal/runtime frames).
  138. - `getException(throwable)`: format a Java `Throwable` (message + stack + causes) as a string.
  139. ### `inspect` - Java object introspection
  140. - `className(obj)`, `simpleClassName(obj)`
  141. - `fields(obj, { includeInherited?, includeStatic? }?)`: enumerate fields (including private).
  142. - `methods(obj, { includeInherited?, includeStatic? }?)`: enumerate methods.
  143. - `getField(obj, fieldName)`: safe field read (`{ ok, value, error? }`).
  144. - `toJson(obj, { maxDepth?, maxArrayLength?, maxStringLength? }?)`: convert common Java objects to JSON-safe structures.
  145. - `isInstance(obj, className)`
  146. - `superclassChain(obj)`
  147. - `interfaces(obj, includeInherited?)`
  148. ### `classes` - discovery and loading
  149. - `find(pattern, { limit? }?)`: search loaded classes by prefix string or RegExp.
  150. - `enumerate(callbackOrOptions?)`: list loaded classes (either returns an array, or streams via callback depending on usage).
  151. - `load(className)`: safe `Java.use` (returns `null` on failure).
  152. - `isLoaded(className)`: quick check if a class is loaded.
  153. - `instances(className, { limit? }?)`: enumerate live heap instances (best-effort, can be expensive).
  154. - `getClassLoader(className)`: get the `ClassLoader` for a loaded class (or `null`).
  155. ### `bytes` - binary helpers
  156. - `toHex(data, { uppercase?, separator? }?)`, `fromHex(hex)`
  157. - `toBase64(data)`, `fromBase64(base64)`
  158. - `fromJavaBytes(byteArray)`, `toJavaBytes(uint8Array)`
  159. - `equals(a, b)`, `concat(...arrays)`, `slice(data, start, end?)`
  160. ### `strings` - conversions and encoding
  161. - `fromJava(javaStringLike)`, `toJava(jsString)`
  162. - `truncate(str, maxLength, ellipsis?)`
  163. - `fromUtf8(data)`, `toUtf8(str)`
  164. - `matches(str, pattern)`
  165. - `safeToString(obj, maxLength?)`
  166. ### `intent` - Intent parsing and construction
  167. - `parse(intent)`: returns a structured summary (action/data/type/categories/component/flags/extras).
  168. - `getExtras(intent)`: extract extras Bundle into a JS object (recurses on nested Bundles).
  169. - `getComponent(intent)`, `isExplicit(intent)`
  170. - `create({ action?, data?, type?, flags?, packageName?, className?, extras? })`: build a new Intent (returns `null` on failure).
  171. - `flagsToStrings(flags)`: decode the bitmask to flag names.
  172. ### `hook` - hook helpers (Java + native)
  173. - `method(className, methodName, { onEnter?, onLeave? })`: hook a method (all overloads if present).
  174. - `methodWithSignature(className, methodName, paramTypes[], { onEnter?, onLeave? })`: hook a specific overload.
  175. - `allOverloads(className, methodName, handler)`: hook all overloads with a single handler.
  176. - `constructor(className, handler)`: hook all `$init` overloads.
  177. - `onClassLoad(className, callback)`: run `callback(Java.use(className))` once the class becomes available.
  178. - `native(addressOrSymbol, callbacks)`: `Interceptor.attach` wrapper for native hooks.
  179. - `replace(classWrapper, methodName, replacement)`: replace implementation and get a restore function.
  180. ### `safe` - fail-closed wrappers
  181. - `java(fn)`: run in `Java.performNow` and return `{ ok, result?, error? }`.
  182. - `call(fn)`: try/catch wrapper returning `{ ok, result?, error? }`.
  183. - `timeout(fn, timeoutMs)`: Promise wrapper returning `{ ok, result?, error? }` (does not cancel underlying work).
  184. - `tryUse(className)`: safe `Java.use` (returns `null` instead of throwing).
  185. - `invoke(obj, methodName, ...args)`: safe method invocation (returns `null` on any failure).
  186. - `get(obj, keyPath, defaultValue?)`: safe property lookup (supports dot paths).
  187. ### `time` - timestamps and rate limiting
  188. - `now()`, `nowMs()`, `hrNow()`
  189. - `format(ms)`, `stopwatch()`
  190. - `sleep(ms)`, `measure(fn)`
  191. - `debounce(fn, delayMs)`, `throttle(fn, intervalMs)`

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.