Skip to content
Back to search

jadx-headless-mcp

MarketplaceWorks with Claude CodeGitHub

jadx-headless: headless jadx MCP for Android APK static analysis.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/1013503897/jadx-headless-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/1013503897/jadx-headless-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/1013503897--jadx-headless-mcp/badge.svg)](/listings/1013503897--jadx-headless-mcp)

HTML

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

Install

Install instructions from the README

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

This repo is also a [Claude Code plugin](https://code.claude.com/docs/en/plugins) — the easiest way to install for Claude Code, no JSON editing and no manual build. It needs **JDK 17+ on `PATH`**; on first start it downloads the released fat jar (SHA-256 verified) and caches it.

/plugin marketplace add 1013503897/jadx-headless-mcp
/plugin install jadx-headless@jadx-headless-mcp

This bundles the MCP server plus the `/jadx-headless:open-apk` skill. See [PLUGIN.md](PLUGIN.md) for how it works, local development (`claude --plugin-dir .`), releasing, and community-marketplace submission. If you'd rather wire the server up by hand (or use another client), use the manual configuration below.

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.

.claude-plugin/marketplace.json · Manifest · 21 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "jadx-headless-mcp",
  3. "owner": {
  4. "name": "w101",
  5. "url": "https://github.com/1013503897"
  6. },
  7. "description": "jadx-headless: headless jadx MCP for Android APK static analysis.",
  8. "plugins": [
  9. {
  10. "name": "jadx-headless",
  11. "source": {
  12. "source": "github",
  13. "repo": "1013503897/jadx-headless-mcp"
  14. },
  15. "description": "Decompile, search and xref Android APKs via ~26 MCP tools over stdio (jadx-core, headless).",
  16. "category": "reverse-engineering",
  17. "keywords": ["android", "apk", "jadx", "decompiler", "reverse-engineering", "static-analysis"],
  18. "license": "Apache-2.0"
  19. }
  20. ]
  21. }
README.md · README · 331 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # jadx-headless-mcp
  2. [![Featured on Made with REA](https://madewithrea.com/badges/featured.svg)](https://madewithrea.com/builds/jadx-headless-mcp-headless-mcp-server-for-llm-driven-apk-analysis)
  3. **English** | [简体中文](README.zh-CN.md)
  4. Headless MCP server for Android APK static analysis, built directly on `jadx-core`. No JADX GUI required, no Python adapter, no plugin to install — just one JVM process speaking MCP over stdio.
  5. ## Why
  6. jadx is two parts: the `jadx-core` decompiler engine, and a GUI wrapped around it for a human to click through by hand.
  7. Give a capable LLM direct access to `jadx-core` and the GUI loses its reason to exist. The model walks the same class tree, resolves the same xrefs, reads the same source — headless and scriptable. As models get stronger, Java-layer reverse engineering increasingly runs end to end from the model, without a reverse engineer driving it by hand.
  8. So this server drops the GUI and exposes `jadx-core` as ~26 MCP tools over stdio.
  9. ## Tools
  10. ### Session management
  11. | Tool | Description |
  12. |---|---|
  13. | `status` | Whether an APK is loaded; path, class/resource counts, load duration |
  14. | `load_apk` | Load an APK / DEX / JAR (replaces any current one) |
  15. | `unload_apk` | Release the loaded APK and free memory |
  16. ### Static analysis (require a loaded APK)
  17. | Tool | Description |
  18. |---|---|
  19. | `get_app_info` | Package name, version, minSdk/targetSdk, permissions |
  20. | `get_android_manifest` | Full decoded AndroidManifest.xml |
  21. | `get_main_activity_class` | LAUNCHER activity FQN |
  22. | `get_main_application_classes_names` | FQNs of classes under the Manifest `package` — a lightweight "is the right APK loaded" probe |
  23. | `list_classes` | Paginated class FQN list |
  24. | `search_classes_by_keyword` | Substring search over class FQNs |
  25. | `get_class_source` | Decompiled Java source. Auto-falls back to smali when jadx hits anti-decompile stubs (marker `// [jadx java-decompile failed → smali]`; `smali_fallback=false` to opt out). Pageable via `offset` (UTF-8 byte offset into full source); header reports `total_bytes`/`next_offset`. Resolves inner/`$Companion` names. |
  26. | `get_class_summary` | Class skeleton (method signatures, fields, inner-class names) — no method bodies |
  27. | `get_smali_of_class` | Smali disassembly. Pageable via `offset` (byte offset into full smali); header reports `total_bytes`/`next_offset` |
  28. | `get_methods_of_class` | Method signatures |
  29. | `get_method_by_name` | Java source of a single method; same smali fallback as `get_class_source` |
  30. | `get_method_body` | One method as Java-if-possible-else-smali, in a JSON envelope (`mode`, `fell_back`, `markers`); handles overloads |
  31. | `get_method_smali` | Smali of a single method (all overloads), sliced from the class disassembly |
  32. | `get_inner_classes` | Inner/nested classes with both dotted `full_name` and raw `$`-joined `raw_name` |
  33. | `resolve_class` | Resolve an inner/`$Companion`/fuzzy class name to its exact FQN, or list candidates |
  34. | `get_fields_of_class` | Field list with types |
  35. | `search_method_by_name` | Global method search (includes inner-class methods) |
  36. | `get_xrefs_to_class` | References to a class |
  37. | `get_xrefs_to_method` | References to a method |
  38. | `get_xrefs_to_field` | References to a field |
  39. | `get_strings` | String resources with optional filter |
  40. | `list_resource_files` | Resource file names |
  41. | `get_resource_file` | Resource file content (text or base64) |
  42. ## Build
  43. Requires JDK 17+.
  44. ```bash
  45. ./gradlew installDist
  46. ```
  47. Output: `build/install/jadx-headless-mcp/bin/jadx-headless-mcp` (and `.bat` on Windows).
  48. For a single portable fat jar:
  49. ```bash
  50. ./gradlew shadowJar
  51. # build/libs/jadx-headless-mcp-<version>-all.jar
  52. ```
  53. > **No build needed?** Prebuilt artifacts (fat jar + distribution zip) are attached to every [GitHub Release](../../releases) — download one and point your MCP config at it directly.
  54. ## Run
  55. Empty start (load an APK later via `load_apk` tool):
  56. ```bash
  57. ./build/install/jadx-headless-mcp/bin/jadx-headless-mcp
  58. ```
  59. Or eager-load on startup:
  60. ```bash
  61. ./build/install/jadx-headless-mcp/bin/jadx-headless-mcp \
  62. --apk /path/to/app.apk \
  63. --max-source-bytes 200000
  64. ```
  65. The server speaks MCP over stdio. Logs go to stderr.
  66. ### Startup options
  67. Pass these as `args` alongside `--apk` / `--max-source-bytes` (all optional; `load_apk` can override the per-APK ones at runtime):
  68. | Flag | Default | Meaning |
  69. |---|---|---|
  70. | `--threads <n>` | `min(CPU, 4)` | jadx pre-decompile worker count (caps peak RAM). `0` = every core. |
  71. | `--include-packages <list>` | — | comma-separated package/FQN prefixes to KEEP (e.g. `com.gcash,com.mynt`); repeatable. Dropped classes are unloaded. |
  72. | `--exclude-packages <list>` | — | comma-separated package prefixes to DROP (e.g. `androidx,kotlin`); repeatable. Combined with include: must match include AND not exclude. |
  73. | `--code-cache-size <n>` | `64` | max decompiled top-level classes kept in RAM (LRU-evicted via `JavaClass.unload()`). `0` = unlimited. |
  74. | `--resources <full\|lite\|none>` | `full` | `full`: all resource files; `lite`: only Manifest + `values/strings` XML + `resources.arsc`; `none`: hide non-manifest resources (`get_strings` unavailable). |
  75. | `--max-scan <n>` | tiered | cap on classes scanned by `search_classes_by_keyword` `code` scope (`0` = built-in defaults: 20000 with a package prefix, 5000 without). |
  76. | `--decompile-timeout-ms <n>` | `90000` | hard wall-clock budget per full-class decompile; prevents one fat obfuscated class from wedging the process. Counts a task's own execution time, not time spent queued behind another request; queue wait is bounded separately at `min(this, 30s)`. |
  77. Run `--help` for the full list (including the `--transport http` remote flags below).
  78. ## Install as a Claude Code plugin
  79. This repo is also a [Claude Code plugin](https://code.claude.com/docs/en/plugins) — the easiest way
  80. to install for Claude Code, no JSON editing and no manual build. It needs **JDK 17+ on `PATH`**; on
  81. first start it downloads the released fat jar (SHA-256 verified) and caches it.
  82. ```
  83. /plugin marketplace add 1013503897/jadx-headless-mcp
  84. /plugin install jadx-headless@jadx-headless-mcp
  85. ```
  86. This bundles the MCP server plus the `/jadx-headless:open-apk` skill. See [PLUGIN.md](PLUGIN.md) for
  87. how it works, local development (`claude --plugin-dir .`), releasing, and community-marketplace
  88. submission. If you'd rather wire the server up by hand (or use another client), use the manual
  89. configuration below.
  90. ## MCP client configuration
  91. `jadx-headless` is a standard stdio MCP server, so any MCP-capable client can drive it — Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Roo Code, VS Code / Copilot, LM Studio, Zed, Codex, Gemini CLI, and others. Claude Code has the smoothest path; the rest take one small config entry — see [Other MCP clients](#other-mcp-clients).
  92. ### Claude Code
  93. #### Quickest: register with the CLI
  94. One command, no JSON editing. `-s user` writes to the global `~/.claude.json`; the default `local` scope only applies to the current project:
  95. ```bash
  96. # installDist launcher
  97. claude mcp add jadx-headless -s user -- C:/tools/jadx-headless-mcp/bin/jadx-headless-mcp.bat
  98. # ...or the portable fat jar (single file; needs java on PATH)
  99. claude mcp add jadx-headless -s user -- java -jar C:/tools/jadx-headless-mcp-<version>-all.jar
  100. ```
  101. Then ask the AI to call `load_apk` with the path you want to analyze. Use `unload_apk` to free memory or switch to a different one — no config edit needed.
  102. #### Or edit the config by hand
  103. Register one entry, swap APKs at runtime:
  104. ```json
  105. {
  106. "mcpServers": {
  107. "jadx-headless": {
  108. "command": "C:/tools/jadx-headless-mcp/bin/jadx-headless-mcp.bat"
  109. }
  110. }
  111. }
  112. ```
  113. To point at the portable fat jar instead:
  114. ```json
  115. {
  116. "mcpServers": {
  117. "jadx-headless": {
  118. "command": "java",
  119. "args": ["-jar", "C:/tools/jadx-headless-mcp-<version>-all.jar"]
  120. }
  121. }
  122. }
  123. ```
  124. If you only ever analyze a single APK and want it ready immediately, append the APK path via `args`:
  125. ```json
  126. {
  127. "mcpServers": {
  128. "jadx-headless": {
  129. "command": "C:/tools/jadx-headless-mcp/bin/jadx-headless-mcp.bat",
  130. "args": ["--apk", "C:/work/current.apk"]
  131. }
  132. }
  133. }
  134. ```
  135. > **Note:** `java -jar` skips the launcher's default JVM args (e.g. `-XX:MaxRAMPercentage=60`). stdout stays clean either way — slf4j-simple logs to stderr and `Main.kt` redirects `System.out` to stderr — but if you need a memory ceiling, pass it yourself via `JAVA_OPTS` / `-XX`. The installDist launcher keeps those defaults.
  136. ### Other MCP clients
  137. Point the client at the same launcher (or `java -jar` the fat jar); only the surrounding config format differs. In every case `command` is the launcher (or `java`), and for the fat jar `args` is `["-jar", "<path-to>-all.jar"]`. `--apk` / `--max-source-bytes` and the `load_apk` / `unload_apk` tools behave identically no matter which client drives it.
  138. **`mcpServers` JSON** — the de-facto standard, accepted by Claude Desktop, Cursor, Windsurf, Cline, Roo Code, LM Studio, Gemini CLI, and most others:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "jadx-headless": {
  143. "command": "C:/tools/jadx-headless-mcp/bin/jadx-headless-mcp.bat"
  144. }
  145. }
  146. }
  147. ```
  148. Only the file it goes in differs — e.g. Claude Desktop `claude_desktop_config.json`, Cursor `.cursor/mcp.json`, Windsurf `~/.codeium/windsurf/mcp_config.json`. Check your client's MCP docs for the exact path.
  149. **VS Code / GitHub Copilot** uses `servers` + `type` (not `mcpServers`), in `.vscode/mcp.json`:
  150. ```json
  151. {
  152. "servers": {
  153. "jadx-headless": {
  154. "type": "stdio",
  155. "command": "C:/tools/jadx-headless-mcp/bin/jadx-headless-mcp.bat"
  156. }
  157. }
  158. }
  159. ```
  160. **TOML-based CLIs** (Codex, Grok, …) use an `mcp_servers` table:
  161. ```toml
  162. [mcp_servers.jadx-headless]
  163. command = "C:/tools/jadx-headless-mcp/bin/jadx-headless-mcp.bat"
  164. args = []
  165. ```
  166. ## Remote mode (`--transport http`)
  167. By default the server speaks stdio, so the MCP client spawns it as a local child process — client and jadx live on the same machine. To split them (client on machine B, jadx **and the APK** on machine A), run the server with the **Streamable HTTP** transport and point a remote MCP client at the URL:
  168. ```bash
  169. # on machine A (where jadx runs and the APK lives)
  170. ./bin/jadx-headless-mcp --transport http --host 0.0.0.0 --port 8080 --allowed-host a.example.com
  171. ```
  172. | Flag | Default | Meaning |
  173. |---|---|---|
  174. | `--transport <stdio\|http>` | `stdio` | serve Streamable HTTP instead of stdio |
  175. | `--host <addr>` | `127.0.0.1` | bind address; use `0.0.0.0` to accept connections from other machines |
  176. | `--port <n>` | `8080` | listen port |
  177. | `--path <p>` | `/mcp` | endpoint path (serves POST/GET/DELETE) |
  178. | `--allowed-host <h>` | — | extra `Host` header value accepted by the DNS-rebinding check (repeatable). Pass the hostname/IP clients use to reach machine A |
  179. | `--no-dns-rebinding-protection` | off | disable `Host`/`Origin` validation (trusted networks / behind a reverse proxy only) |
  180. The endpoint is `http://<host>:<port><path>` (default `http://127.0.0.1:8080/mcp`). Point any Streamable-HTTP-capable MCP client at it — e.g. Claude Code:
  181. ```bash
  182. claude mcp add --transport http jadx-headless http://a.example.com:8080/mcp
  183. ```
  184. **The APK always lives on the jadx host.** `load_apk` resolves its `path` with `File(path)` on the machine running the server (A) — a remote client only sends a path string that must be valid on A. Copy the APK to A first, then call `load_apk` with the A-side path. It's still one APK per process; multiple HTTP sessions share the single loaded APK.
  185. **Security:**
  186. - **DNS-rebinding protection is on by default** and only allows loopback `Host` headers, so a remote client reaching `a.example.com` is rejected with `403` unless you add `--allowed-host a.example.com` (or disable the check). This deliberately stops a malicious web page from driving your server.
  187. - The endpoint has **no authentication**. Prefer binding to `127.0.0.1` and reaching it over an SSH tunnel, or put it behind a reverse proxy / VPN that adds auth. Don't expose `0.0.0.0` on an untrusted network.
  188. ## Architecture
  189. ```
  190. Claude Code ──stdio | Streamable-HTTP JSON-RPC──> jadx-headless-mcp (JVM)
  191. │
  192. ├── MCP Kotlin SDK (stdio / Ktor CIO HTTP server)
  193. │
  194. └── SessionHolder
  195. │ (Mutex-serialized load/unload)
  196. └── JadxSession
  197. └── JadxDecompiler (jadx-core)
  198. ```
  199. Lazy decompilation: only `get_class_source` and `get_smali_of_class` (and `get_method_by_name` / `code` search) trigger per-class decompilation. Index building at startup is metadata-only.
  200. **Important:** `max_bytes` truncates the response **after** jadx finishes materializing the class — it does **not** stop a slow decompile early. Fat obfuscated classes (e.g. large ViewModels) previously could block the whole MCP process for tens of minutes until the client’s multi-hour tool ceiling. As of the decompile-timeout fix:
  201. - Server hard timeout: `--decompile-timeout-ms` (default **90000**)
  202. - On timeout the tool returns an `// ERROR: ... timed out ...` banner immediately
  203. - Prefer `get_class_summary` + `get_method_by_name` for large classes
  204. ## Memory tuning
  205. The launcher sets `-XX:MaxRAMPercentage=60.0` by default. Override via `JAVA_OPTS`:
  206. ```bash
  207. JAVA_OPTS="-Xmx8g" ./bin/jadx-headless-mcp
  208. ```
  209. ## Upstream tracking
  210. | Dependency | Mechanism |
  211. |---|---|
  212. | `io.github.skylot:jadx-core` and friends | Dependabot weekly (opens PRs grouped under "jadx"); CI verifies the build still passes |
  213. | `io.modelcontextprotocol:kotlin-sdk` | Dependabot weekly (grouped under "mcp-kotlin-sdk") |
  214. | `org.jetbrains.kotlinx:*` | Dependabot weekly (grouped under "kotlinx") |
  215. | GitHub Actions versions | Dependabot monthly |
  216. Related but **not** auto-synced (different architecture; manual watch only):
  217. - [`zinja-coder/jadx-ai-mcp`](https://github.com/zinja-coder/jadx-ai-mcp) — JADX GUI plugin
  218. - [`zinja-coder/jadx-mcp-server`](https://github.com/zinja-coder/jadx-mcp-server) — Python adapter for the above
  219. - [`mobilehackinglab/jadx-mcp-plugin`](https://github.com/mobilehackinglab/jadx-mcp-plugin) — alternative GUI plugin
  220. If those projects ship a new tool worth porting, file an issue here.
  221. ## Used by
  222. - **[REA](https://github.com/morluto/rea)** (`morluto/rea`) integrates this project as an upstream analysis engine for its static Android APK analysis. [`third_party/README.md`](https://github.com/morluto/rea/blob/main/third_party/README.md) .
  223. Pinning this engine by digest in your own project? Each release's `jadx-headless-mcp.sha256` asset (and the current release's [`.mcp.json`](.mcp.json) pin) lets you verify a download the same way — see below.
  224. ## Release verification (SHA-256)
  225. Every [GitHub Release](../../releases) attaches the portable fat jar `jadx-headless-mcp-<version>-all.jar`, a distribution zip, and (since v0.7.1) a `jadx-headless-mcp.sha256` asset carrying that fat jar's SHA-256. The `.sha256` asset is the authoritative digest for each release; the current release's digest is also pinned in the Claude Code plugin's [`.mcp.json`](.mcp.json).
  226. To verify a download, compare its digest against the release's `jadx-headless-mcp.sha256` asset (or the `.mcp.json` pin):
  227. ```bash
  228. # macOS / Linux
  229. sha256sum jadx-headless-mcp-<version>-all.jar
  230. ```
  231. ```powershell
  232. # Windows PowerShell
  233. (Get-FileHash -Algorithm SHA256 jadx-headless-mcp-<version>-all.jar).Hash.ToLowerInvariant()
  234. ```
  235. > **Maintainer note:** the release's `jadx-headless-mcp.sha256` asset and the [`.mcp.json`](.mcp.json) pin carry the same digest — keep the two in sync when releasing.
  236. ## Acknowledgements
  237. - [`skylot/jadx`](https://github.com/skylot/jadx) — the underlying decompiler
  238. - [`modelcontextprotocol/kotlin-sdk`](https://github.com/modelcontextprotocol/kotlin-sdk) — MCP server framework
  239. ## License
  240. Apache-2.0.

Ratings and comments

Sign in to rate this skill.

Sign in

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