jadx-mcp

# jadx-mcp MCP (Model Context Protocol) server as a jadx-gui plugin. Lets an AI client (Claude Code, Claude Desktop, or any MCP client) analyze the app currently loaded in jadx-gui: list/search classes, fetch decompiled Java or smali, per-method source, manifest components (main activity, application package), resources and `strings.xml`, cross-references (class/method/field level), and renames (class/method/field/package/variable) for deobfuscation loops. Native implementation on the official [MCP Java SDK](https://java.sdk.modelcontextprotocol.io/latest/) - no Python shim, no external process. Server runs inside jadx-gui over streamable HTTP; host and port are configurable in the plugin's settings dialog (`127.0.0.1:8090` by default). ## Requirements - jadx-gui **1.5.6** (plugin API target). - **jadx-gui running on Java 17+** (the MCP SDK and the plugin jar are Java 17 bytecode). The `jadx-gui-x.y.z-with-jre-win` bundle ships a recent JRE and works out of the box. If you launch `jadx-gui.bat` with a system JDK, check `java -version` first: on an older JVM jadx cannot load the plugin (`UnsupportedClassVersionError` in the jadx log). - To build: JDK 17+ and Gradle (or use the Gradle wrapper). ### Launching the right JVM (Windows) - `jadx-gui.exe` (with-JRE bundle) uses its bundled JRE - always Java 17+, use this. - `jadx-gui.bat` uses the system `JAVA_HOME`. If yours is older than 17, point it at a recent JDK first: ```powershell $env:JAVA_HOME = "<custom_dir_location>" jadx-gui.bat ``` The plugin is Java 17 bytecode by design: the official MCP Java SDK (2.x) is records-based and requires Java 17+, and mixing bytecode levels caused classloader issues in jadx's plugin loader. Keep jadx-gui on a JVM >= 17. ## Build Prerequisites: JDK 17+ (toolchain pinned to 21, any newer JDK works) and Gradle 9.x on the PATH. jadx-core and slf4j are `compileOnly` - no jadx install needed to build. PowerShell: ```powershell cd jadx-mcp # if your default JAVA_HOME is not a JDK 17+, point Gradle at one: $env:JAVA_HOME = "<custom_dir_location>" gradle jar # fat jar -> build/libs/jadx-mcp-0.1.0.jar gradle smoke # headless e2e check: loads a real jar into jadx, starts the server on an # ephemeral port, runs raw JSON-RPC calls (initialize, tools/list for all # 27 tools, status, get_all_classes, get_class_source, get_method_by_name, # xrefs, renames, non-APK error paths) and stops it; prints "SMOKE OK" ``` What the jar contains: - Own classes (`jadxmcp/*`), compiled with `--release 17`. - MCP Java SDK 2.0.1 + Jackson 3 + Reactor + embedded Jetty 12 (ee11, servlet 6.1), unpacked into one fat jar (no shadow plugin; signatures and `module-info.class` stripped). Jetty instead of Tomcat because the jadx with-JRE bundle ships a stripped jlink runtime without `java.management`, which Tomcat requires. - `META-INF/services/jadx.api.plugins.JadxPlugin` — the ServiceLoader entry jadx picks up. - Transitive `org.slf4j:slf4j-api` is excluded so jadx's own slf4j binding wins. Build layout: ``` src/main/java/jadxmcp/ JadxMcpPlugin (entry), McpServerManager (Jetty + MCP lifecycle), JadxTools (all MCP tools), Settings (host+port persistence) src/main/resources/META-INF/services/jadx.api.plugins.JadxPlugin src/test/java/jadxmcp/ SmokeTest (run by gradle smoke) ``` Gradle details worth knowing if you touch the build: - `gradle clean jar smoke` for a from-scratch verify. - Toolchain comes from `java.toolchain` in `build.gradle.kts` — Gradle auto-downloads JDK 21 if `JAVA_HOME` doesn't provide it; setting `JAVA_HOME` just makes it instant. - To bump versions: `val jadxVersion` (plugin API target) and the `mcp` / `jetty-ee11-servlet` coordinates in `build.gradle.kts`. `requiredJadxVersion` in `JadxMcpPlugin` must match the jadx line you target. - `gradle smokeLimited` runs the same smoke test restricted to the jadx with-JRE module set (no `java.management`, no `jdk.unsupported`) — use it after any dependency change to make sure the server still loads in the stripped runtime. ## Install ``` jadx plugins --install-jar jadx-mcp-0.1.0.jar ``` or copy the jar to `~/.jadx/plugins/` and restart jadx-gui. If an older version is installed, delete it first (same plugin id, duplicate jars in the plugins dir). ## Use 1. jadx-gui → open an APK/DEX/JAR. 2. Menu **Plugins → jadx-mcp: Settings...** opens the single settings dialog: - **Host** (default `127.0.0.1`) and **Port** (default `8090`) — saved to `~/.jadx/jadx-mcp.properties` on Start. - **Start** starts (or restarts with new host/port) the server; **Stop** stops it; the status line shows the running URL. No need to close the dialog: status updates live. - **Warning:** binding a non-loopback host (e.g. `0.0.0.0` or a LAN IP) exposes the server to the network — there is no authentication. 3. Register with your MCP client (URL from the status line). **Claude Code** (one-shot, no config editing): ``` claude mcp add --transport http jadx-mcp http://localhost:8090/mcp ``` With a non-default host/port, use the URL from the status dialog. Scope flag as needed: `--scope project` writes `.mcp.json` in the repo, default is user-local. **Claude Desktop** - edit `claude_desktop_config.json` (Settings → Developer → Edit Config) and add under `mcpServers`: ```json { "mcpServers": { "jadx-mcp": { "type": "http", "url": "http://localhost:8090/mcp" } } } ``` Restart Claude Desktop after editing. Both clients speak streamable HTTP, which is what the plugin serves. 4. Stop with the **Stop** button in the same dialog (server also stops on jadx exit). ### Smoke test (no client) PowerShell: ```powershell $h = @{ Accept = "application/json, text/event-stream" } $b = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' $r = Invoke-WebRequest -Method Post http://localhost:8090/mcp -ContentType "application/json" -Headers $h -Body $b $r.Headers["mcp-session-id"] # session id -> server works ``` ## Tools 27 tools, all validated against a JSON schema by the SDK. Paginated tools take optional `offset`/`limit` (default 50, max 500). | Tool | Notes | |---|---| | `status` | app loaded, class/package/resource counts, manifest package | | **Classes** | | | `get_all_classes` | paginated, optional package prefix filter | | `search_classes` | class name contains, case-insensitive | | `get_class_source` | decompiled Java source (original or alias name) | | `get_smali_of_class` | DEX disassembly | | `search_classes_by_keyword` | full-text over decompiled code (`class:line:source` matches), paginated; expensive on large apps | | `fetch_current_class` | class the analyst is viewing in jadx-gui (node under caret), with source | | **Methods / fields** | | | `get_method_by_name` | single method source; `signature` fragment disambiguates overloads | | `search_method_by_name` | method name contains across all classes, paginated | | `get_methods_of_class` | methods with flags, signatures, return types | | `get_fields_of_class` | fields with flags and types | | **Manifest (APK)** | | | `get_android_manifest` | decoded AndroidManifest.xml | | `get_manifest_component` | one component type (activity, activity-alias, service, receiver, provider), optional name filter | | `get_main_activity_class` | MAIN/LAUNCHER activity, with source | | `get_main_application_classes_names` | class names in the manifest application package, paginated | | `get_main_application_classes_code` | their full sources, paginated (default 10 per page — token heavy) | | **Resources** | | | `get_strings` | decoded `res/values/strings.xml` | | `get_all_resource_file_names` | paginated, optional path filter | | `get_resource_file` | decoded content of one resource | | **Renames (mutate the jadx project)** | | | `rename_class` | short new name, GUI refresh included | | `rename_method` | `signature` fragment disambiguates overloads | | `rename_field` | | | `rename_package` | full new package name, cascades to all classes in it | | `rename_variable` | local var in a method; session-local (not persisted to saved jadx metadata) | | **Xrefs** | | | `xrefs_to_class` | all references to the class, paginated | | `xrefs_to_method` | references + override-related methods, paginated | | `xrefs_to_field` | methods accessing the field, paginated | Domain errors (class not found, no app loaded, binary resource, ambiguous overload) come back as `isError` tool results so the LLM can self-correct. ## Security - Binds `127.0.0.1` by default; Origin/Host allowlist is built from the configured host. - Origin/Host header validation (`http://localhost:*` / `localhost:*`) to block DNS-rebinding and cross-origin requests from web pages. - No auth: keep it on localhost. Do not port-forward. ## Known limits - **No `get_selected_text`** — the jadx plugin API (1.5.6 `JadxGuiContext`) exposes the node under the caret, not the raw text selection. `fetch_current_class` is the closest equivalent. - **No `debug_get_*` tools** (stack frames, threads, variables) — the plugin API has no debugger access. Use the jadx-gui debugger UI directly. - `rename_variable` is session-local: the new name shows in reloaded code but is not written to saved jadx metadata (`.jadx` files), unlike the class/method/field/package renames which go through the standard deobfuscation alias system. - Comments and headless (jadx-cli) operation are not implemented.