rea-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 tomainor avX.Y.Ztag publishesghcr.io/eguthriewastaken/rea-mcp(latestandsha-<12>formain,X.Y.Zandsha-<12>for a tag).docker pull ghcr.io/eguthriewastaken/rea-mcp:latestworks without credentials, and the published image passes the smoke test (seedocs/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, objdumpWhat 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_scenariotool does exactly that, as uid 99), write to/workand/tmp, and reach the network./samplesstays read-only. Treat the key like a shell password and readdocs/SECURITY.mdbefore 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/healthzanswers{"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 cleandocker 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:
Copy it to the flash drive under the name
my-rea-mcp.xml(unRAID lists user templates asmy-*.xmlin 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.)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.)
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 bynobody:users).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 |
| none, required (or one of the next two) | One API key, at least 32 characters |
| none | Path to a file holding one key (a trailing newline is trimmed); for Docker or unRAID secrets |
| none | Comma-separated keys, for rotation. All three sources are combined |
|
| Port the gateway listens on inside the container |
|
| Open sessions at once, one REA and one Ghidra process each. Over the limit: |
|
| 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 |
|
|
|
| empty | Comma-separated |
|
|
|
| empty | The address the agent's |
|
| Largest single upload. A proxy in front may allow less |
|
| Most |
|
| How long an unused upload or download URL stays valid (30 to 86400) |
|
| A tool result longer than this (as serialized JSON) is stored and replaced by a short stub. |
| empty (REA's | Maximum Java heap of each Ghidra process, such as |
| empty (REA's | How long REA waits for Ghidra to start |
| empty (off) | An absolute path, recommended |
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 callsclose_binaryonly if you tell it to (it never did unprompted). The session, its Ghidra (about 1.2 GB) and its slot stay untilSESSION_IDLE_TIMEOUT_SECpasses.So finished conversations use up
MAX_SESSIONS. At the defaults (4 sessions, 300 s), four conversations within five minutes make the server answer503to the next one, which then has noreatools; 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 calledclose_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. Withclose_binaryin 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
The agent calls
request_uploadwith a file name. It gets a one-timeupload_url, a ready-madecurlcommand, and thepaththe file will have in the container.It runs the
curlcommand 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 withsha256sum).It calls REA's
open_binarywith the returnedpath(/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
/samplesshare as before.Set
PUBLIC_BASE_URL(for examplehttps://<host>) when the container is behind a tunnel or proxy. Without it the URL is built from the request'sHostheader withhttp://, which a proxy that redirectshttptohttps(Cloudflare does, with a301thatcurldoes not follow) turns into a failed upload. WithTRUST_PROXY=truethe proxy'sX-Forwarded-ProtoandX-Forwarded-Hostare used instead.request_uploadsays 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>/inboxon the host (/work/inboxin 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: truedoes). 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 fullrequest_uploadsays 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 own413page (Ran on one tunnel;docs/CLOUDFLARE.md), so setMAX_UPLOAD_BYTES=104857600there. For larger files use the/samplesshare, or setPUBLIC_BASE_URLto an address on your own network.upload_statusshows 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_offsetsays where to continue and isnullat 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-timecurldownload of the whole result, so the agent can search it withgrepin its own shell. It checks thesha256it is given.Asking REA for less (
detail: "summary", a smallermax_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/resultsis emptied when the container starts); a session can store at most 256 MiB. A session ends afterSESSION_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 answers410with 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 fromSESSION_IDLE_TIMEOUT_SEC). The session's open binary goes with it: after a long pause REA answersNo app is open(REA's own words), the connector reconnects by itself into a new, empty session, and the agent must callopen_binaryagain 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, raiseSESSION_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 theoutputSchemaof REA's tools, because a stub cannot satisfy them and a client that validates would reject it. The text the model reads is unchanged.)40000is 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 thecurlcommand it returns from your shell, then callopen_binarywith the returnedpath. If a result comes back withtruncated: true, read it withread_result(orrequest_downloadandgrep); do not ask me to paste it. When you finish with a binary, callclose_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_binaryor is reaped (afterSESSION_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 orSIGTERM). 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_IDandREA_GHIDRA_DISABLED_ANALYZERSare 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 |
What the server can do, isolation limits, key rotation, hardening | |
Exposing it through a Cloudflare Tunnel | |
Architecture and the evidence behind every claim, including what is still UNVERIFIED | |
The requirements, and the proposals, designs and tasks behind them; the first change is archived there ( | |
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/orwork/.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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Remote MCP server exposing SMI Aware tools, resources, and skills over Streamable HTTP.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Related MCP Servers
- AlicenseAqualityCmaintenanceA 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.11180Apache 2.0
- AlicenseNot gradedqualityBmaintenanceLifts local stdio MCP servers into remote Streamable HTTP endpoints for cloud-hosted AI clients, with bearer-token auth and tool policy filtering.12 npmMIT
- FlicenseNot gradedqualityDmaintenanceA local, privacy-first MCP server that orchestrates Ghidra, Binary Ninja, x64dbg, and system tools to provide AI assistants with powerful binary analysis capabilities.-
- AlicenseAqualityCmaintenanceMCP 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.109MIT