Recaf MCP
MCP server plugin for Recaf β enabling AI agents to perform Java reverse engineering
Ask AI about Recaf MCP
Powered by Claude Β· Grounded in docs
I know everything about Recaf MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
recaf-mcp
MCP (Model Context Protocol) server plugin for Recaf, enabling AI agents to perform Java reverse engineering tasks.
3 tools across 2 categories for Cloudflare-style Code Mode workflows: dynamic tool discovery and Groovy scripting.
Quick Start
- Install the plugin β download the JAR and drop it into Recaf's plugin directory
- Start Recaf β open a JAR/APK/class file, the MCP server starts automatically on
localhost:8085 - Connect your tool β point your AI coding assistant at the MCP endpoint
- Start with discovery β call
search-toolsto find relevant tools before calling task-specific tools - Optional scripting β enable
execute-recaf-scriptonly when needed (disabled by default)
Starting From Scratch
- Install Recaf 4.x and Java 22+.
- Install the plugin JAR into your Recaf plugins directory.
- Launch Recaf (safe default mode):
# from recaf-mcp/recaf-mcp-plugin while developing
./gradlew runRecaf
- Connect your MCP client to:
http://localhost:8085/mcp
- Open your target JAR/APK/class in Recaf.
- Call
search-toolsfirst, then use task-specific tools. - Only if you need Groovy scripting, restart Recaf with explicit opt-in:
RECAF_MCP_SCRIPT_EXECUTION_ENABLED=true ./gradlew runRecaf
You can also enable with JVM property:
java -Drecaf.mcp.script.execution.enabled=true -jar recaf.jar
Prerequisites
Installation
Plugin (Recaf)
Option A: Download release
Download recaf-mcp-plugin-0.2.0.jar from the Releases page and copy it to your Recaf plugins directory:
| OS | Plugin Directory |
|---|---|
| Linux | ~/.config/Recaf/plugins/ |
| macOS | ~/Library/Application Support/Recaf/plugins/ |
| Windows | %APPDATA%/Recaf/plugins/ |
Option B: Build from source
git clone https://github.com/tha23rd/recaf-mcp.git
cd recaf-mcp/recaf-mcp-plugin
./gradlew shadowJar
Then copy build/libs/recaf-mcp-plugin-0.2.0.jar to your plugins directory (see table above).
Stdio Bridge (optional)
The stdio bridge is needed for tools that communicate via stdin/stdout instead of HTTP (e.g., Claude Desktop).
cd recaf-mcp
uv tool install ./recaf-mcp-bridge
This installs the recaf-mcp-bridge command globally.
Connecting Your AI Tool
Claude Code
HTTP mode (recommended β no bridge needed):
claude mcp add --transport http recaf http://localhost:8085/mcp
Stdio mode (if HTTP transport is not supported):
claude mcp add recaf -- recaf-mcp-bridge
Other Tools (Cursor, VS Code, Codex, OpenCode, etc.)
If the tool supports HTTP/SSE MCP servers, point it at:
http://localhost:8085/mcp
This is a Streamable HTTP endpoint. Example configurations:
VS Code / Cursor (.vscode/mcp.json)
{
"servers": {
"recaf": {
"type": "http",
"url": "http://localhost:8085/mcp"
}
}
}
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"recaf": {
"command": "recaf-mcp-bridge",
"args": []
}
}
}
If the tool only supports stdio, use the bridge:
recaf-mcp-bridge [--host localhost] [--port 8085]
Tools
| Category | Tools | Description |
|---|---|---|
| Tool Discovery | search-tools | Query-driven discovery of available MCP tools by keyword |
| Groovy Scripting | describe-recaf-api, execute-recaf-script | Multi-step reverse-engineering workflows in a single tool call |
Code Mode Workflow
For token-efficient agent workflows, use this sequence:
search-toolswith a short query (script,api,workspace,search) to find relevant toolsdescribe-recaf-apito retrieve only the API sections needed for scriptingexecute-recaf-scriptto combine multiple analysis steps in one roundtrip
Code Mode responses are not globally text-truncated. execute-recaf-script still enforces timeout and stdout byte caps for stability.
This follows Cloudflare's query-driven Code Mode pattern for MCP tool discovery: https://blog.cloudflare.com/code-mode-mcp/
Code Mode Script Security
execute-recaf-script is guarded by an explicit runtime policy and is disabled by default.
- Enable script execution only when needed by setting
RECAF_MCP_SCRIPT_EXECUTION_ENABLED=trueor-Drecaf.mcp.script.execution.enabled=true. - Exposed Groovy bindings are intentionally minimal:
workspace,decompilerManager,searchService,callGraphService,inheritanceGraphService, andout. - Script execution is time-bounded, stdout is capped, and timeout handling interrupts execution with loop/method interruption checks applied at compile time.
This feature executes user-provided code inside the Recaf JVM. Keep it disabled for untrusted sessions and enable it only for controlled workflows.
Configuration
| Setting | Default | Description |
|---|---|---|
RECAF_MCP_HOST / -Drecaf.mcp.host | 127.0.0.1 | Bind address |
RECAF_MCP_PORT / -Drecaf.mcp.port | 8085 | Listen port |
-Drecaf.mcp.format | toon | Response format: toon (token-optimized, ~36% smaller) or json |
RECAF_MCP_SCRIPT_EXECUTION_ENABLED / -Drecaf.mcp.script.execution.enabled | false | Enables execute-recaf-script (disabled by default for safety) |
Environment variables take priority over system properties.
Headless Mode (CI / Containers)
Recaf ships a built-in --headless flag that skips the UI but keeps the
plugin lifecycle intact. The MCP server comes up cleanly and serves all
tools over HTTP. Verified on Linux with Recaf 4.x + plugin 0.2.0:
- ~2.1 s boot to MCP listener (vs ~3 s full UI)
- ~875 MB steady-state RSS (β33 % less than full UI)
search-tools,describe-recaf-api,execute-recaf-scriptall respond- SSVM auto-discovers a JDK 11β17 install for boot classes
- No
DISPLAY, no GTK runtime, no Monocle native libs required
Launch
JavaFX modules must still be on the module path β Recaf's CDI scan loads
beans that reference javafx.* types even though no Stage is created.
The display itself is never opened.
# locate the JavaFX 22.0.1 jars Recaf already pulls in
JFX_BASE=$(find ~/.gradle/caches -name 'javafx-base-22*linux*.jar' | head -1)
JFX_GRAPHICS=$(find ~/.gradle/caches -name 'javafx-graphics-22*linux*.jar' | head -1)
JFX_CONTROLS=$(find ~/.gradle/caches -name 'javafx-controls-22*linux*.jar' | head -1)
java \
--module-path "$JFX_BASE:$JFX_GRAPHICS:$JFX_CONTROLS" \
--add-modules javafx.controls,javafx.graphics,javafx.base \
--add-opens java.base/java.lang=ALL-UNNAMED \
--add-opens java.base/java.lang.reflect=ALL-UNNAMED \
--add-opens java.base/java.io=ALL-UNNAMED \
-jar recaf.jar --headless --input /path/to/target.jar
Add RECAF_MCP_SCRIPT_EXECUTION_ENABLED=true to the environment if you
need execute-recaf-script (still off by default).
Notes & limitations
- The
--inputflag is currently required in headless mode β there is no MCPopen-workspacetool yet, so the agent can only operate on the workspace specified at launch. Multi-target sessions need a UI restart until that tool lands. - Dropping the JavaFX module path entirely fails CDI bootstrap with
Failed to create Recaf CDI container. The jars are required even though the toolkit never starts. - JavaFX's Monocle backend is not needed and is not present in the
standard
javafx-graphics-*-linux.jarpublished since JDK 11. Don't bother trying-Dglass.platform=Monocleβ Recaf's native--headlessflag bypasses the Application launch path entirely.
Response Format
Tool responses use TOON by default, a token-optimized serialization format that reduces wire size by ~36% compared to JSON. This saves tokens when working with LLMs. Set -Drecaf.mcp.format=json to use plain JSON instead.
E2E Validation
Validated end-to-end using ./gradlew runRecaf and a real workspace JAR (SKlauncher-3.2.18.jar):
- Opened workspace directly in the Recaf UI
- Verified
search-toolsdiscovers bothdescribe-recaf-apiandexecute-recaf-script - Verified
describe-recaf-apikeyword filtering - Verified default policy blocks
execute-recaf-scriptwith explicit opt-in guidance - Verified
execute-recaf-scriptsucceeds whenRECAF_MCP_SCRIPT_EXECUTION_ENABLED=true
Building & Development
# Build plugin
cd recaf-mcp-plugin
./gradlew shadowJar
# Run tests
./gradlew test
# Build + deploy + launch Recaf (dev convenience)
./gradlew runRecaf
# Install bridge for development
cd ../recaf-mcp-bridge
uv sync
uv run recaf-mcp-bridge --help
