Configuration
MCGhidra is configured through environment variables. No configuration file is required — defaults work out of the box for local development.
MCP Server
Section titled “MCP Server”These variables control the Python MCP server process.
| Variable | Default | Description |
|---|---|---|
GHIDRA_HOST | localhost | Hostname for connecting to Ghidra instances. Change this when Ghidra runs on a remote host. |
MCGHIDRAMCP_DEBUG | unset | Set to 1 to enable DEBUG-level logging. Shows HTTP requests, pagination details, and discovery results. |
MCGHIDRA_FEEDBACK | true | Enable or disable feedback collection. Set to false to disable. |
MCGHIDRA_FEEDBACK_DB | ~/.mcghidra/feedback.db | Path to the SQLite database for feedback data. The parent directory is created automatically. |
Internal Defaults
Section titled “Internal Defaults”These values are set in MCGhidraConfig and are not currently exposed as environment variables, but can be overridden programmatically when creating the server:
| Setting | Default | Description |
|---|---|---|
quick_discovery_range | 18489-18498 | Port range for quick instance discovery scans |
full_discovery_range | 18400-18599 | Port range for full discovery scans (instances_discover) |
request_timeout | 30.0s | HTTP request timeout for Ghidra API calls |
discovery_timeout | 0.5s | HTTP timeout per port during discovery scans |
default_page_size | 50 | Default pagination page size |
max_page_size | 500 | Maximum allowed page size |
cursor_ttl_seconds | 300 | Cursor expiration time (5 minutes) |
max_cursors_per_session | 100 | Maximum active cursors per MCP session |
max_response_tokens | 8000 | Hard token budget — the return_all guard triggers above this |
expected_api_version | 2 | Minimum API version required from the Ghidra plugin |
Docker Image
Section titled “Docker Image”These variables control the MCP server’s Docker integration — how it builds, tags, and starts containers.
| Variable | Default | Description |
|---|---|---|
MCGHIDRAMCP_VERSION | latest | Docker image tag to use when starting containers. |
MCGHIDRA_PORT | 8192 | Default port for container API mapping. Overridden by auto-allocation in multi-container mode. |
MCGHIDRA_MAXMEM | 2G | Max JVM heap size passed to containers. Increase for large binaries. |
MCGHIDRA_DOCKER_AUTO | false | When true, the server will automatically start a Docker container when a binary is loaded and no Ghidra instance is available. |
Port Pool
Section titled “Port Pool”The port pool prevents conflicts when multiple MCP sessions run containers simultaneously. Ports are allocated using flock-based locking.
| Variable | Default | Description |
|---|---|---|
MCGHIDRA_PORT_START | 8192 | First port in the allocation pool. |
MCGHIDRA_PORT_END | 8319 | Last port in the allocation pool (128 ports total). |
MCGHIDRA_PORT_LOCK_DIR | /tmp/mcghidra-ports | Directory for port lock files. Created automatically on first use. |
Port lock files are named port-{N}.lock and contain JSON with the session ID, PID, and timestamp. The docker_cleanup tool removes stale locks from crashed processes.
Container Environment
Section titled “Container Environment”These variables are read by the Docker entrypoint script (entrypoint.sh) inside the container. They configure how Ghidra runs in headless mode.
Core Settings
Section titled “Core Settings”| Variable | Default | Description |
|---|---|---|
MCGHIDRA_MODE | headless | Container operating mode. See modes below. |
MCGHIDRA_PORT | 8192 | HTTP API port inside the container. The MCP server maps this to a host port from the pool. |
MCGHIDRA_MAXMEM | 2G | Max JVM heap size. Passed to Ghidra’s analyzeHeadless command. |
Ghidra Paths
Section titled “Ghidra Paths”| Variable | Default | Description |
|---|---|---|
GHIDRA_HOME | /opt/ghidra | Ghidra installation directory inside the container. |
SCRIPT_DIR | /home/ghidra/ghidra_scripts | Directory for Ghidra Python scripts (MCGhidraServer.py lives here). |
PROJECT_DIR | /projects | Directory where Ghidra stores its project files (.gpr, .rep). |
PROJECT_NAME | MCGhidra | Name of the Ghidra project created for the imported binary. |
Firmware Import Options
Section titled “Firmware Import Options”These are optional. When omitted, Ghidra auto-detects the binary format.
| Variable | Default | Description |
|---|---|---|
GHIDRA_LANGUAGE | auto-detect | Processor language ID. Must match ARCH:ENDIAN:SIZE:VARIANT format (e.g., ARM:LE:32:v4t). Setting this causes the container to use BinaryLoader unless GHIDRA_LOADER overrides it. |
GHIDRA_BASE_ADDRESS | auto-detect | Base address for raw binaries. Hex format: 0x00000000 or 00000000. |
GHIDRA_LOADER | auto-detect | Loader type override. Common values: BinaryLoader (raw bytes), AutoImporter (header-based detection). Must be alphanumeric with underscores. |
Container Modes
Section titled “Container Modes”The MCGHIDRA_MODE variable selects the operating mode:
| Mode | Description |
|---|---|
headless | Default. Imports the binary, runs auto-analysis, starts the HTTP API server. This is what docker_auto_start and docker_start use. |
server | Opens an existing project (no import). Requires a program name as an argument. Useful for re-analyzing a previously imported binary. |
analyze | Imports and analyzes a binary, then exits. No HTTP server. Use for batch processing. |
shell | Drops into an interactive bash shell. Useful for debugging the container environment. |
Validation
Section titled “Validation”All firmware import parameters are validated before reaching Ghidra:
GHIDRA_LANGUAGEmust matchARCH:ENDIAN:SIZE:VARIANT(regex-validated).GHIDRA_BASE_ADDRESSmust be valid hex, max 64-bit.GHIDRA_LOADERmust be alphanumeric with underscores.
Invalid values are rejected with a descriptive error before any Docker or Ghidra operations run. The MCP server validates these on the client side as well, so errors surface in tool responses rather than buried in container logs.