Skip to main content
Glama

rea-mcp

REA + Ghidra as a remote MCP server, packaged for unRAID.

Status. The gateway, the Docker image and the unRAID template are built and were verified on an unRAID 7.3.4 host (evidence: docs/DESIGN.md, section 11). The image is published: a push to main or a vX.Y.Z tag publishes ghcr.io/eguthriewastaken/rea-mcp (latest and sha-<12> for main, X.Y.Z and sha-<12> for a tag). docker pull ghcr.io/eguthriewastaken/rea-mcp:latest works without credentials, and the published image passes the smoke test (see docs/DESIGN.md, section 12). Claude Code has been run end to end against the container, and the maintainer has run the claude.ai connector against it through a Cloudflare Tunnel (what that showed: docs/DESIGN.md, section 18.3).

A single Docker container that exposes REA ("Reverse Engineer Anything", npm package rea-agents) and its analysis engines (Ghidra, tshark, objdump) as a remote MCP server over streamable HTTP, so it can be added as a custom connector in Claude and used from Claude Code.

REA is a local stdio MCP server. This project is a thin gateway that starts one REA process per MCP session and serves it over HTTP, authenticating every request with a static API key in an x-api-key header.

Claude (connector or Claude Code) -> HTTPS (a tunnel or proxy you run; not part of this project)
  -> container:8080  gateway (API key, session cap, keep-alives)
     -> one REA process per session (stdio)
        -> Ghidra (headless), tshark, objdump

What it can analyze: the files in the folder you mount read-only at /samples. The image has Ghidra 12.1.4 (on a Temurin JDK 21), tshark 4.0 and GNU objdump, and no JADX and no Rizin, so APK decompilation and Rizin commands are not available (REA answers those with a capability_unavailable error).

The API key is powerful. A client that has it can make the container run commands (REA's capture_process_scenario tool does exactly that, as uid 99), write to /work and /tmp, and reach the network. /samples stays read-only. Treat the key like a shell password and read docs/SECURITY.md before you expose the server.

Quick start

You need Docker and a folder of files you are permitted to analyze. The image is linux/amd64 only.

# Get the image: pull the published one, or build it yourself (it downloads Ghidra and a JDK, each checked
# against a pinned SHA-256).
docker pull ghcr.io/eguthriewastaken/rea-mcp:latest
#   or: docker build -f docker/Dockerfile -t rea-mcp:local .   (then use rea-mcp:local below)

# A key of at least 32 characters. Keep it: every client needs it. There is no default.
export REA_MCP_API_KEY="$(openssl rand -hex 32)"

docker run -d --name rea-mcp \
  --cap-drop=ALL --security-opt=no-new-privileges:true \
  -e REA_MCP_API_KEY -p 8080:8080 \
  -v <samples-dir>:/samples:ro \
  -v <work-dir>:/work \
  ghcr.io/eguthriewastaken/rea-mcp:latest
  • <work-dir> must be writable by uid 99, gid 100 (the user the container runs as). If it is not, the container exits at once with a one-line JSON error that names the directory.

  • curl http://localhost:8080/healthz answers {"status":"ok"} without a key.

  • The MCP endpoint is http://localhost:8080/mcp. The server speaks plain HTTP; put TLS in front of it before exposing it beyond your own machine (docs/CLOUDFLARE.md).

  • Run scripts/smoke_test.sh <image> to check an image: health, identity, 401 without a key, refusal without a key, and a clean docker stop.

Related MCP server: Levitate

Install on unRAID

The template is unraid/rea-mcp.xml. It is not in Community Apps (that was decided against), so install it as a user template:

  1. Copy it to the flash drive under the name my-rea-mcp.xml (unRAID lists user templates as my-*.xml in this directory, read from its Docker manager code):

    curl -fsSL -o /boot/config/plugins/dockerMan/templates-user/my-rea-mcp.xml \
      https://raw.githubusercontent.com/EGuthrieWasTaken/rea-mcp/main/unraid/rea-mcp.xml

    (That URL works once this is on main. Until then copy the file from a clone.)

  2. On the Docker tab choose Add Container and pick rea-mcp from the user templates. (unRAID's Template repositories field is an alternative; unRAID's own help text marks it deprecated.)

  3. Fill in the three blanks: the API key (openssl rand -hex 32; the field is masked), the Samples folder (a dedicated folder, mounted read-only) and, if you like, the Work directory (default /mnt/user/appdata/rea-mcp, which must be writable by nobody:users).

  4. Apply. The thirteen settings under "advanced" are the variables below.

The template runs the container with --security-opt=no-new-privileges:true --cap-drop=ALL, bridge networking and no web UI. unRAID adds --pids-limit 2048 itself (its Docker PID Limit setting, default 2048). The image's latest tag moves with every merge to main; for a stable install pin a version tag, for example ghcr.io/eguthriewastaken/rea-mcp:0.1.0 (the first release is v0.1.0; releases are listed on the repository's Releases page).

Two unRAID host settings that matter

Both are on the Settings, Docker page and apply to every container; a template cannot change them.

  • Docker Stop Timeout (default 10 s). With checkpointing off the container stops in under a second. With checkpointing on, stopping a session may take up to 30 s so REA can save, and the gateway's shutdown budget is 40 s, so raise the Stop Timeout to at least 40 s. Otherwise Docker kills the container after 10 s and unsaved annotations may be lost (a kill never corrupts a checkpoint). Whether array stop and server shutdown use the same setting was not checked.

  • Docker PID Limit (default 2048). Measured: a live Ghidra session used about 94 PIDs on a 64-CPU host, so the default of 4 sessions needs roughly 400. The count follows the CPU count; on a bigger or busier host, watch it. Four concurrent sessions were not run.

Configuration

Every setting is an environment variable. An unparsable value makes the container exit non-zero and name the variable. A variable set to nothing counts as unset.

Variable

Default

Meaning

REA_MCP_API_KEY

none, required (or one of the next two)

One API key, at least 32 characters

REA_MCP_API_KEY_FILE

none

Path to a file holding one key (a trailing newline is trimmed); for Docker or unRAID secrets

REA_MCP_API_KEYS

none

Comma-separated keys, for rotation. All three sources are combined

PORT

8080

Port the gateway listens on inside the container

MAX_SESSIONS

4

Open sessions at once, one REA and one Ghidra process each. Over the limit: 503 with Retry-After, and nothing is evicted

SESSION_IDLE_TIMEOUT_SEC

300

A session with no request and no call in flight for this long is ended. Read Tell the agent to close what it opens before leaving the default

TRUST_PROXY

false

true only behind a trusted proxy or tunnel: the client address then comes from CF-Connecting-IP or X-Forwarded-For

ALLOWED_HOSTS

empty

Comma-separated Host names accepted on /mcp and on the upload and download URLs (case-insensitive, port ignored). Empty accepts any. /healthz is exempt

LOG_LEVEL

info

debug, info, warn or error. Logs never contain request headers or keys

PUBLIC_BASE_URL

empty

The address the agent's curl uses to reach the container, for upload and download URLs: https://<host>, nothing after the host. Set it behind a tunnel or proxy. See Giving the agent a file

MAX_UPLOAD_BYTES

268435456 (256 MiB)

Largest single upload. A proxy in front may allow less

INBOX_MAX_BYTES

4294967296 (4 GiB)

Most /work/inbox may hold, counting uploads in progress. Nothing deletes from it

TRANSFER_TICKET_TTL_SEC

900

How long an unused upload or download URL stays valid (30 to 86400)

RESULT_INLINE_LIMIT_CHARS

40000

A tool result longer than this (as serialized JSON) is stored and replaced by a short stub. 0 turns that off; otherwise 2000 to 10000000

GHIDRA_MAX_HEAP

empty (REA's 2G)

Maximum Java heap of each Ghidra process, such as 4G or 512M

REA_GHIDRA_STARTUP_TIMEOUT_MS

empty (REA's 330000)

How long REA waits for Ghidra to start

REA_GHIDRA_CHECKPOINT_DIR

empty (off)

An absolute path, recommended /work/checkpoints. See Checkpoints

The image also fixes JAVA_HOME=/opt/jdk, GHIDRA_INSTALL_DIR=/opt/ghidra and HOME=/work/home; do not override them. Mounts: /samples (read-only) and /work (read-write; Ghidra output, a directory per session under sessions/, the inbox/ of uploaded files, results/ for large results, and the checkpoint folder).

Memory. Each session has its own Ghidra, so size MAX_SESSIONS times GHIDRA_MAX_HEAP plus overhead against your RAM. Measured: two sessions analyzing a 770 KB static binary at the default 2G heap peaked at about 2.5 GiB for the container.

The key

Generate one at run time with openssl rand -hex 32 and enter it only in the unRAID form, an environment variable or a secret. The server refuses to start with no key, or with any key shorter than 32 characters. To rotate: add the new key to REA_MCP_API_KEYS next to the old one, move the clients, then remove the old key.

Connect a client

Both clients send the key in an x-api-key header. Use <host> for the public host name of your tunnel or proxy and <key> for your key; never paste a real key into a document or a repository.

Claude Code (syntax from Claude Code's MCP documentation; the --header form is the one it shows):

claude mcp add --transport http rea https://<host>/mcp --header "x-api-key: <key>"
# or, to try it locally:
claude mcp add --transport http rea http://localhost:8080/mcp --header "x-api-key: <key>"

The command line ends up in your shell history. To keep the key out of it and out of Claude Code's configuration file, export it (export REA_KEY=<key>) and give the header in single quotes so the shell does not expand it: --header 'x-api-key: ${REA_KEY}'. Claude Code expands ${REA_KEY} when it loads the server (checked with a configuration passed on the command line, which connected; claude mcp add --scope project wrote the placeholder and not the key to .mcp.json, but that server was still awaiting approval, so it was not connected). A server added with --scope project (shared in .mcp.json) must be approved once by running claude. Then ask Claude Code to list the rea tools. This was run end to end against the container with Claude Code 2.1.319 in claude -p mode: all 255 tools appear, and an analysis of a sample works.

After you update the server, refresh the connector. The Claude desktop app was seen quoting the previous tool descriptions (and showing no tool titles) after the server had been updated, so it keeps the list it fetched when the connector was connected. Reconnect the connector, and if the new descriptions still do not appear, remove and re-add it (which action refreshes it was not checked: UNVERIFIED).

claude.ai custom connector (steps from Anthropic's help page; run by the maintainer against this server, see section 18.3 of docs/DESIGN.md): open Customize, Connectors, choose + Add, Add custom connector, enter https://<host>/mcp, and under Request headers add x-api-key with your key; choose No sign in for authentication. Claude reaches the server from Anthropic's cloud, on port 443 only, so it must be public HTTPS on the standard port; a private address or :8080 will not work.

Long calls, keep-alives and timeouts

Ghidra analysis takes tens of seconds (11 s for a 16 KB binary and 41 to 45 s for a 770 KB static one, measured), and a proxy in front will cut a silent connection. The gateway writes an SSE comment on every open stream every 15 s, so such a call stays alive, and it forwards REA's progress notifications. A session with a call in flight is never reaped as idle. Cloudflare documents a default 125 s proxy read timeout (the design planned for roughly 100 s); keep-alives defeat an idle timeout but not an absolute cap on duration. Details: docs/CLOUDFLARE.md.

Tell the agent to close what it opens

Add a line like this to your instructions: "When you finish with a binary, call close_binary." It releases Ghidra and, with checkpoints on, saves your edits and frees the binary for the next session.

This matters because of what Claude Code was observed to do (version 2.1.319, claude -p; interactive use and the claude.ai connector were not tested):

  • Every conversation gets its own session (its own REA and Ghidra).

  • It does not end its session when it finishes. It sends no DELETE /mcp, and the agent calls close_binary only if you tell it to (it never did unprompted). The session, its Ghidra (about 1.2 GB) and its slot stay until SESSION_IDLE_TIMEOUT_SEC passes.

  • So finished conversations use up MAX_SESSIONS. At the defaults (4 sessions, 300 s), four conversations within five minutes make the server answer 503 to the next one, which then has no rea tools; it works again once an idle session is reaped. With checkpoints on, a new conversation on the same binary is refused ("another REA session owns this checkpoint") until the previous conversation's session is reaped or has called close_binary.

  • The timeout trades slots against a quiet conversation's open binary. The default is 300 s (it was 900 s until this was seen). A conversation that is quiet for longer than the timeout loses its session; Claude Code reconnects by itself, but the new session has nothing open, so the agent must open the binary again (it did, in the test) and unsaved edits are gone. Lower it to free slots sooner; raise it (and MAX_SESSIONS, with RAM to match) if your conversations pause for long. With close_binary in your instructions, the checkpoint lock-out is gone either way.

Giving the agent a file, and reading large results

Two things a chat cannot carry: a file you want analyzed, and the whole of a large analysis result. The gateway adds four tools beside REA's so that neither has to pass through the model.

Handing the agent a file

  1. The agent calls request_upload with a file name. It gets a one-time upload_url, a ready-made curl command, and the path the file will have in the container.

  2. It runs the curl command from its own shell. The bytes go from there to your server; the model never sees them. curl prints the saved size and SHA-256 (the agent can compare it with sha256sum).

  3. It calls REA's open_binary with the returned path (/work/inbox/<name>) and carries on.

curl -sS --fail-with-body -T ./sample.dll 'https://<host>/upload/<id>/<secret>'
# {"ok":true,"upload_id":"u_...","name":"sample.dll","path":"/work/inbox/sample.dll","size":79691776,"sha256":"..."}
  • The agent needs a shell that can reach your server. Claude Code on your own machine can. Whether the claude.ai code-execution sandbox can reach your host name depends on its network allowlist (UNVERIFIED here). Without a shell, copy the file into the /samples share as before.

  • Set PUBLIC_BASE_URL (for example https://<host>) when the container is behind a tunnel or proxy. Without it the URL is built from the request's Host header with http://, which a proxy that redirects http to https (Cloudflare does, with a 301 that curl does not follow) turns into a failed upload. With TRUST_PROXY=true the proxy's X-Forwarded-Proto and X-Forwarded-Host are used instead. request_upload says which rule it used (url_source).

  • A URL works once and expires after TRANSFER_TICKET_TTL_SEC (15 minutes). The URL is the authorization, so it should not be pasted anywhere else; the agent asks for a new one to retry.

  • Where the files go. <work-dir>/inbox on the host (/work/inbox in the container), one folder shared by every session, so a file uploaded once can be opened by a later conversation. By default an upload does not replace a file of the same name (overwrite: true does). A file only appears under its name once it has arrived whole, and a failed upload leaves nothing behind.

  • Nothing deletes from the inbox. It is capped by INBOX_MAX_BYTES; when it is full request_upload says so, and you clear it from the share. Files are never made executable.

  • Limits. One upload is at most MAX_UPLOAD_BYTES. A proxy in front can have a lower limit of its own; through a Cloudflare Tunnel, bodies up to exactly 100 MiB (104,857,600 bytes) were accepted and one byte more was refused with Cloudflare's own 413 page (Ran on one tunnel; docs/CLOUDFLARE.md), so set MAX_UPLOAD_BYTES=104857600 there. For larger files use the /samples share, or set PUBLIC_BASE_URL to an address on your own network.

  • upload_status shows progress and the outcome of an upload, if curl's output is lost.

Reading large results

REA's results are often big: a plain list_strings on a 371 KB program returned 340,324 characters, and a client will not take that much in one piece. When a result is longer than RESULT_INLINE_LIMIT_CHARS, the gateway stores the whole text under /work/results and sends a short stub instead:

{"truncated": true, "result_id": "r_...", "tool": "list_strings", "chars": 340324, "bytes": 340324,
 "preview": "<the first 2000 characters>", "stored": true, "note": "..."}
  • read_result (result_id, offset, length) reads it in pieces. Offsets count bytes; a piece never cuts a character in half; next_offset says where to continue and is null at the end. The slice comes back as plain text, not escaped. It is analysis output from an untrusted file, so REA's "untrusted content" marking is kept.

  • request_download (result_id) gives a one-time curl download of the whole result, so the agent can search it with grep in its own shell. It checks the sha256 it is given.

  • Asking REA for less (detail: "summary", a smaller max_output_bytes, a narrower range) also helps, and costs no extra calls.

  • A session's stored results are deleted when the session ends (and /work/results is emptied when the container starts); a session can store at most 256 MiB. A session ends after SESSION_IDLE_TIMEOUT_SEC (5 minutes by default) without any request, so an agent that pauses for longer (waiting for you to approve a shell command, say) finds its result and its download URL gone: the URL then answers 410 with a message saying so, and the agent has to run the call again. The tools' descriptions and messages state the actual time (they are built from SESSION_IDLE_TIMEOUT_SEC). The session's open binary goes with it: after a long pause REA answers No app is open (REA's own words), the connector reconnects by itself into a new, empty session, and the agent must call open_binary again before repeating anything. Any call to the REA tools restarts the timer, and so does the end of an upload or download the session started. If your agents pause a lot, raise SESSION_IDLE_TIMEOUT_SEC; it costs session slots (see below).

  • To turn all of this off, set RESULT_INLINE_LIMIT_CHARS=0: results and REA's own tool schemas are then relayed exactly as REA sent them. (While it is on, the gateway removes the outputSchema of REA's tools, because a stub cannot satisfy them and a client that validates would reject it. The text the model reads is unchanged.)

  • 40000 is a guess below the one size that was seen to fail (58,842 characters through the claude.ai connector). Lower it if your client still complains; raise it if it copes.

Tell the agent how to use them

Add a line like this to your instructions:

When I give you a file, call request_upload, run the curl command it returns from your shell, then call open_binary with the returned path. If a result comes back with truncated: true, read it with read_result (or request_download and grep); do not ask me to paste it. When you finish with a binary, call close_binary.

These tools do not shorten a long analysis. A call that the client gives up on after a few minutes (it did, at about 3 minutes, on a 76 MiB DLL) is a separate problem; see docs/DESIGN.md, section 18.3.

Keeping analysis between sessions (checkpoints)

By default each session analyzes from scratch and Ghidra's work, including names and comments you add, is discarded when the session ends. Set REA_GHIDRA_CHECKPOINT_DIR=/work/checkpoints and REA saves its Ghidra analysis of each binary and restores it in later sessions (measured: 8.8 s against 43.5 s for the first analysis of a 770 KB binary, with names and comments intact). It is off by default because of these trade-offs, all observed with a real Ghidra:

  • Shared. Names and comments saved in one conversation appear in any later one that opens the same bytes.

  • One live session per binary. A second session on the same binary fails at once with "another REA session owns this checkpoint" until the first calls close_binary or is reaped (after SESSION_IDLE_TIMEOUT_SEC). A conversation that reconnects can be blocked by its own idle session.

  • All or nothing. With it on, anything that is not a stock ELF, PE or Mach-O import (a raw binary, say) fails to open with Ghidra instead of falling back.

  • Saved when: after the first analysis, on close_binary, and when a session ends or the container stops (a closed stdin or SIGTERM). A kill loses edits made since the last save but never corrupts it.

  • Never pruned. Delete old entries yourself. Keep the folder on persistent storage, separate from /samples. One folder serves one container.

  • Needs Docker Stop Timeout of at least 40 s on unRAID (above).

  • REA_GHIDRA_PROJECT_PATH, REA_GHIDRA_SEED_FILE, REA_GHIDRA_NATIVEAOT_JAR, REA_GHIDRA_LANGUAGE_ID and REA_GHIDRA_DISABLED_ANALYZERS are never passed on to REA, because REA refuses them beside a checkpoint folder.

Whether running unRAID's "New Permissions" tool on the work folder resets the checkpoint folders (REA insists on mode 700) was not tested.

Hardening, and running read-only

The container runs as uid 99, gid 100 with no capabilities, and /samples read-only. It also works with --read-only if you mount a writable /tmp: --read-only --tmpfs /tmp:rw,size=1g (tested with Docker's default noexec 64 MB tmpfs). Size /tmp generously: each live session used about 27 MiB for a 770 KB binary. See docs/SECURITY.md.

Where to read more

File

Contents

docs/SECURITY.md

What the server can do, isolation limits, key rotation, hardening

docs/CLOUDFLARE.md

Exposing it through a Cloudflare Tunnel

docs/DESIGN.md

Architecture and the evidence behind every claim, including what is still UNVERIFIED

openspec/specs/, openspec/changes/

The requirements, and the proposals, designs and tasks behind them; the first change is archived there (npx @fission-ai/openspec validate --all --strict)

openspec/config.yaml, CLAUDE.md

Hard constraints for every change

Ground rules

  • No secrets in this repository, ever. The API key is supplied at runtime only. There is no default key.

  • No third-party software under analysis (including TI software) is bundled, downloaded into the repository, or committed. Never commit anything under samples/ or work/.

  • Only analyze software you are permitted to analyze.

License

Copyright (C) 2026 rea-mcp contributors.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3. It is distributed WITHOUT ANY WARRANTY. See LICENSE for the full text (GPL-3.0-only).

REA (rea-agents) is a separate MIT-licensed project and Ghidra a separate Apache-2.0-licensed one (with some GPL components); neither is part of this repository. The image carries their licence files (/opt/ghidra/LICENSE, /opt/ghidra/licenses, /opt/jdk/NOTICE, /opt/jdk/legal) and this project's own at /app/LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A multi-backend MCP server that exposes binary analysis capabilities from IDA Pro and Ghidra, allowing LLMs to directly drive reverse-engineering tools via natural language.
      11
      180
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lifts local stdio MCP servers into remote Streamable HTTP endpoints for cloud-hosted AI clients, with bearer-token auth and tool policy filtering.
      12 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local, privacy-first MCP server that orchestrates Ghidra, Binary Ninja, x64dbg, and system tools to provide AI assistants with powerful binary analysis capabilities.
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP server integrating Rizin reverse engineering, RzGhidra decompiler, and capa for binary analysis, enabling LLMs to open binaries, identify capabilities, extract function addresses, and decompile to C pseudocode.
      10
      9
      MIT