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

1. Install the plugin — download the JAR and drop it into Recaf's plugin directory
2. Start Recaf — open a JAR/APK/class file, the MCP server starts automatically on localhost:8085
3. Connect your tool — point your AI coding assistant at the MCP endpoint
4. Start with discovery — call search-tools to find relevant tools before calling task-specific tools
5. Optional scripting — enable execute-recaf-script only when needed (disabled by default)

Starting From Scratch

1. Install Recaf 4.x and Java 22+.
2. Install the plugin JAR into your Recaf plugins directory.
3. Launch Recaf (safe default mode):

# from recaf-mcp/recaf-mcp-plugin while developing
./gradlew runRecaf

4. Connect your MCP client to:

http://localhost:8085/mcp

5. Open your target JAR/APK/class in Recaf.
6. Call search-tools first, then use task-specific tools.
7. 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

• Recaf 4.x (snapshot build)
• Java 22+
• Python 3.11+ and uv (only if using the stdio bridge)

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:

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:

{
  "servers": {
    "recaf": {
      "type": "http",
      "url": "http://localhost:8085/mcp"
    }
  }
}

{
  "mcpServers": {
    "recaf": {
      "command": "recaf-mcp-bridge",
      "args": []
    }
  }
}

If the tool only supports stdio, use the bridge:

recaf-mcp-bridge [--host localhost] [--port 8085]

Tools

Code Mode Workflow

For token-efficient agent workflows, use this sequence:

1. search-tools with a short query (script, api, workspace, search) to find relevant tools
2. describe-recaf-api to retrieve only the API sections needed for scripting
3. execute-recaf-script to 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=true or -Drecaf.mcp.script.execution.enabled=true.
• Exposed Groovy bindings are intentionally minimal: workspace, decompilerManager, searchService, callGraphService, inheritanceGraphService, and out.
• 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

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-script all 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 --input flag is currently required in headless mode — there is no MCP open-workspace tool 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.jar published since JDK 11. Don't bother trying -Dglass.platform=Monocle — Recaf's native --headless flag 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-tools discovers both describe-recaf-api and execute-recaf-script
• Verified describe-recaf-api keyword filtering
• Verified default policy blocks execute-recaf-script with explicit opt-in guidance
• Verified execute-recaf-script succeeds when RECAF_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