git clone https://github.com/x746b/mem_forensics-mcp.git
cd mem_forensics-mcp
# Full install (recommended)
uv sync --extra full
# Minimal (Vol3 only, no YARA/VT)
uv sync --extra volatility3
Build Rust Engine (optional)
Prebuilt binaries ship for aarch64-linux and x86_64-linux in engines/memoxide/. The server auto-detects the host architecture. To build from source:
# Requires Rust toolchain (https://rustup.rs)
cd engines/memoxide-src
cargo build --release
# Binary lands at engines/memoxide-src/target/release/memoxide
# The server auto-detects it (prefers local build over prebuilt)
Configure Volatility3 (optional)
If Vol3 is installed at /opt/volatility3 it's auto-detected. Otherwise: export VOLATILITY3_PATH="/path/to/volatility3"
Verify
uv run python -m mem_forensics_mcp.server
# Should show: Rust engine: available, Volatility3: available
Add to an MCP client
Register mem-forensics-mcp as a local stdio server in your MCP client's settings. Configuration format and location depend on the client. For clients that accept mcpServers JSON, use:
Replace the command with the absolute path to the virtual environment's Python interpreter. For a source checkout, this is /path/to/mem_forensics-mcp/.venv/bin/python3 after uv sync. For a PyPI install, use the .venv created during installation. If your client uses a different configuration format, enter the same command and arguments through its MCP server settings.
If Volatility3 is installed in a custom location, set VOLATILITY3_PATH to its absolute path in the server's environment settings (for example, "env": {"VOLATILITY3_PATH": "/path/to/volatility3"} in the JSON example). Use the client's MCP server list to confirm it connects.
Quick Start
# 1. Initialize
memory_analyze_image(image_path="/evidence/memory.raw")
# 2. Full triage
memory_full_triage(image_path="/evidence/memory.raw")
# 3. Drill down
memory_run_plugin(image_path="/evidence/memory.raw", plugin="malfind", pid=1234)
memory_analyze_image reports readiness at two levels:
ready and session_ready: an engine opened the image and the session can be reused.
raw_ready: OS-agnostic Rust operations such as search and readraw are available.
structured_ready: symbols/profile data is sufficient for structure-aware plugins.
ready remains a compatibility alias for session_ready; it does not imply that
Volatility process, network, or command plugins can run. Check os_type,
structured_ready, capabilities, and warnings before choosing those tools.
For Linux structure-aware analysis, provide either a symbol directory or an
explicit ISF file. Linux ISFs are never downloaded or generated automatically:
Without a matching ISF, LiME images still expose raw search and readraw.
The analysis response includes the exact kernel banner and a suggested ISF
filename. With symbols loaded, process tree routes to linux.pslist.PsList,
command history routes to linux.bash.Bash, and generic Linux Volatility
plugins are available through memory_run_plugin.
Tool Reference
Core
Tool
Tier
Description
memory_analyze_image
1->2
Initialize image, auto-detect profile
memory_run_plugin
1->3
Run any plugin (Rust or Vol3)
memory_list_plugins
-
List available plugins
memory_list_sessions
-
List active sessions
memory_get_status
-
Show engine status
Analysis
Tool
Tier
Description
memory_full_triage
1+2
Complete automated investigation
memory_hunt_process_anomalies
2
DKOM detection, parent-child validation
memory_get_process_tree
2
Process tree with suspicious highlighting
memory_find_injected_code
1->2
Code injection + YARA scanning
memory_find_c2_connections
1+2
Network C2 detection
memory_get_command_history
1+2
Command recovery + classification
memory_extract_credentials
2
Hash/secret extraction via Vol3
Extraction
Tool
Tier
Description
memory_dump_process
2
Process info and loaded DLLs
memory_dump_vad
2
Examine memory region details
memory_list_dumpable_files
3
List cached files
Threat Intelligence
Tool
Description
vt_lookup_hash
VirusTotal hash lookup
vt_lookup_ip
VirusTotal IP reputation
vt_lookup_domain
VirusTotal domain reputation
vt_lookup_file
Hash file + VT lookup
Example: Full Triage Output
Running memory_full_triage on a Windows 10 memory dump (Win10 19041, x64, VMware):