volatility-mcp

A local, client-neutral MCP server for evidence-backed queries with official Volatility 3. It runs your separately installed Volatility executable, saves complete outputs and execution records, and exposes small, controlled tools over stdio. It makes no LLM API calls and needs no model API key.

An optional investigation and reporting workflow lives in the same repository. Individual queries do not require reports, templates, case-report metadata, or Codex. No report is generated as a side effect of a tool call.

An experimental local Workbench optionally adds a browser interface for case selection, readiness, reports, evidence and follow-up questions.

This is an independent project, not endorsed by the Volatility Foundation, OpenAI, or Dragos. Original project material is MIT licensed; see third-party notices.

Quick start 1: use the MCP server

Prerequisites

• Python 3.12 or newer, Git, and a local MCP client that supports stdio.

• Official Volatility 3, installed separately. Setup can reuse an existing installation or create one.

• Enough storage for the image, complete outputs, symbol cache, and optional dumps.

• A stable, readable acquisition copy you are authorized to analyze.

The verified local target is macOS on Apple silicon with native ARM64 Python 3.12 and Volatility 3 2.28.2. Platform and client checks, their scope, and remaining limitations are recorded in VALIDATION.md. Linux analysis-host support is unverified; Windows hosts are currently unsupported because process management uses POSIX primitives. A plugin importing successfully does not establish support for every guest OS, symbol set, or image.

Clone this repository using its GitHub Code URL, enter the clone directory, then create the server environment:

python3 -c 'import platform, sys; print(sys.executable, platform.machine())'
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock.txt
.venv/bin/python -m pip install --no-deps -e .

On Apple silicon the architecture must be arm64. If Python is missing or running through Rosetta, install a suitable native build from python.org, then recreate only the new server environment with that interpreter. Do not move an existing virtual environment: its executable paths are not portable.

Reuse an existing working Volatility environment:

.venv/bin/python -m volatility_mcp setup \
  --config "$PWD/config.local.json" \
  --vol-python "$HOME/Forensics/volatility-env/bin/python" \
  --vol "$HOME/Forensics/volatility-env/bin/vol" \
  --evidence-root "$HOME/Forensics/cases" \
  --output-root "$HOME/Forensics/outputs"

For a new installation, replace the two --vol-* options above with --install-volatility. This uses the official volatility3[full] package from PyPI in a separate environment; it does not add Volatility to the MCP environment. Use setup --help for an alternate Volatility environment location. Setup is idempotent: a suitable installation is reused, and existing evidence is retained.

Put .raw, .mem, .vmem, .dmp, .lime, or .dd acquisitions in the evidence root, optionally in case subfolders. These are accepted filename extensions, not a promise that every file or acquisition format is supported by Volatility. Keep archives separately and extract only intended memory images after validating the archive; the server does not unpack archives. Source files should be read-only.

Verify a real MCP handshake and discovery call:

.venv/bin/python -m volatility_mcp doctor --config "$PWD/config.local.json" --mcp

Connect a client

For any stdio MCP client, configure the absolute server Python as the command and these separate arguments:

command: <clone>/.venv/bin/python
args: ["-m", "volatility_mcp", "serve", "--config", "<clone>/config.local.json"]

Replace <clone> with your clone's absolute path; do not paste angle-bracket placeholders literally. Alternatively set VOLATILITY_MCP_CONFIG to the absolute JSON configuration path. There is no HTTP listener, bearer token, or server-side model credential. Configure your client's tool timeout above the configured subprocess timeout, allowing extra time for hashing large images and discovery.

For local Codex CLI, this helper backs up the previous registration and Codex configuration before registering the server and configuring compatible timeouts:

.venv/bin/python -m volatility_mcp register-codex \
  --config "$PWD/config.local.json" \
  --backup-dir "$HOME/Forensics/config-backups"
codex mcp list
codex mcp get volatility --json
codex -C "$PWD" --no-daemon

The underlying supported registration command is:

codex mcp add volatility -- "$PWD/.venv/bin/python" \
  -m volatility_mcp serve --config "$PWD/config.local.json"

The helper sets startup and tool timeouts to at least 90 and 1,800 seconds, respectively, increasing them for configured execution limits and preserving larger existing values and unrelated settings. CLI registration listing proves configuration exists; doctor --mcp and an actual client tool call prove protocol/tool operation. After code or configuration changes, exit the old session and launch the command above to use a fresh server process. See the official Codex MCP documentation.

Keep other configuration editors idle during registration. If registration or its verification fails, the helper restores the previous configuration atomically when the observed file has not changed again. If it detects a concurrent change, it leaves the newer contents intact and reports the private backup for comparison.

Codex CLI runs on your computer and can use the configured local server. It can use a ChatGPT sign-in; the MCP server itself requires no extra model API key. An ordinary browser ChatGPT conversation cannot directly access this local stdio server or your memory-image files. Analysis is local, but excerpts returned through MCP can be sent to the connected AI service; read SECURITY.md before analyzing sensitive acquisitions.

First request in your connected client:

Use the volatility MCP tools to list memory images and discover installed plugins. For example.vmem, identify the guest OS, then run its appropriate process-list plugin. Cite saved output and report failures explicitly. Do not create a report.

The file must actually exist beneath the configured evidence root. No example image or malware is distributed here.

Related MCP server: Volatility MCP

Available tools

Discover names and options rather than relying on older Volatility cheat sheets. For example, call list_plugins with {"query":"pslist"}, choose the appropriate OS-specific match, inspect its schema, then call run_plugin with an exact name and arguments such as [] or ["--pid", "1234"]. Do not pass shell command strings. Refer to live tools/list for complete schemas.

For saved reconstructions, get the run ID from case_history and the exact run-relative artifact path from that run's manifest. Call inspect_artifact with image, run_id, artifact (for example json/files/reconstructed.dmp) and operation: "pe" or "strings". String pages expose file offsets, encoding, next_offset, and truncation; follow the cursor to continue. Results and provenance are saved privately and reused when source/parser/settings identity still matches. No Volatility analysis or full-image hash is needed for this inspection.

The pinned, pure-Python pefile dependency parses headers; nothing recovered is executed. Header-declared DLL/executable flags, structural range checks, and parser warnings are separate from maliciousness and completeness. Printable extraction covers U+0020..U+007E in ASCII or UTF-16LE, not all Unicode. See ARTIFACT_INSPECTION.md for limits and examples. After upgrading, install the updated requirements.lock.txt and restart idle clients/Workbench to expose the updated MCP tools.

Execution, evidence, and recovery

• Input paths must resolve inside the evidence root; symlink escapes, shell syntax, arbitrary plugin directories, and output overrides are rejected. Plugin options and value types are checked against the installed catalog. Execution uses argument arrays with shell=False; there is no generic shell tool. A discovered regex contract has narrowly scoped pattern validation: the windows.vadregexscan.VadRegExScan --pattern value accepts valid byte-regex punctuation, bounded to 4,096 UTF-8 bytes with no literal control characters. Other string/path restrictions and plugin execution timeouts remain in force.

• On a reuse miss, the plugin runs once with Volatility's JSON renderer. Complete stdout, stderr, execution metadata, and any extracted files stay in the configured output directory. A readable text view is derived from saved JSON without another scan. Conversion failures retain the original bytes and an explicit error.

• Run records include source fingerprints and SHA-256 before/after execution, tool versions, exact arguments, timestamps, status, and artifact hashes. Local compatibility-addon runs also preserve the addon source and its hash.

• Analysis is serialized across backend processes sharing an output root. Timeouts, cancellation, client disconnects, and graceful shutdown retain partial output and status. Forced termination can leave child processes or interrupted records; inspect them before retrying. Failed or incomplete work is never a clean finding.

• Output previews are bounded; read_output pages saved text in chunks of at most 65,536 bytes, and case_history provides paginated execution summaries. These are byte reads, not structured row/field queries.

Persistent result reuse applies to every client using the backend, including the discovery probes in get_image_info. Equivalent requests reuse a successful, integrity-verified run after restart, retaining its run ID and artifact paths. The identity includes the source fingerprint/SHA-256, typed arguments, file inputs, analyzer/plugin/dependency code and versions, symbols/cache content, and execution configuration. Changed context or damaged artifacts prevents reuse. A filesystem lock prevents concurrent duplicate analysis within the same output root.

Responses indicate reused and include hashing measurements; reuse receipts are saved separately without editing the original run. Full source hashes before and after each request remain mandatory, including hits. Hashing seconds, bytes, and file counts are recorded by phase; no integrity shortcuts were introduced. Catalog refresh and dependency/artifact hashing still take time, so a hit is not an instant lookup. Plugin timeouts exclude this overhead.

Older runs without the new identity are preserved but cannot be safely reused. Failed/incomplete runs are never hits. If symbols/cache or other inputs change during a successful run, that run remains available but is not reuse-eligible; a subsequent request executes again against the stable context. Separate output roots do not share results or locks. See RESULT_REUSE.md for the identity, receipts, measurements, and recovery limits.

The included xpnet.XpNetScan is a local compatibility addon, separate from official Volatility plugins. It carves Windows XP x86 TCPT/TCPA pool candidates; stale or damaged allocations are possible. It cannot prove active connection state, traffic, or malicious communication. Official Windows NetScan/NetStat may reject XP. Discover actual compatibility and retain the exact failure.

Optional pypykatz plugin

pypykatz-volatility3 is a third-party addon for Mimikatz-style credential extraction from saved Windows LSASS memory. It is not bundled with this project or an official Volatility Foundation plugin. Extracted credentials do not establish that Mimikatz previously ran on the captured system.

Install pypykatz into the configured Volatility environment, not the MCP server environment, and place the author's vol_pypykatz.py in that environment's volatility3/plugins/ directory. Retain the upstream license and record the source commit/hash; keep installation records and local assets outside tracked files. Existing MCP configuration then discovers it without allowing arbitrary plugin directories in tool arguments. Installing the dependency alone does not install the Volatility plugin file.

The verified local combination is pypykatz 0.6.13, upstream plugin commit 1b722f0, and Volatility 2.28.2 / Python 3.12 / ARM64 macOS. Dependency checks, CLI plugin help, and discovery through both an existing MCP session and a fresh registered stdio connection passed, with no plugin import failures. Existing analyzer package versions were preserved. No image was opened or credentials extracted for this verification; runtime compatibility with individual guest OS/images is untested.

Call list_plugins with {"query":"pypykatz"}; the exact installed name is vol_pypykatz.pypykatz, with no additional plugin arguments. If an idle client or Workbench retains an older plugin catalog, reconnect/restart it. The catalog's installed_volatility origin describes installation location, not endorsement; the upstream wrapper reports an inherited version of 0.0.0, separate from the pypykatz dependency version. Treat any extracted secrets as sensitive case output.

An LSA signature not found! failure is returned as lsa_signature_not_found with acquisition/parser guidance. On XP/NT5, the follow-on error Template guessing is not applicable for NT5 does not mean the plugin is missing. Missing pages or an unsupported binary layout may prevent recovery. Preserve the failed run; repeating the same extraction cannot restore missing memory, and failure does not establish credential absence or theft.

Quick start 2: optionally use investigation and reporting

After the MCP quick start succeeds, read the versioned report specification and use prompts/GENERATE_REPORT.md in a client that can read the repository and write your chosen private case-output folder. With local Codex, give that folder workspace write access, for example:

codex -C "$PWD" --add-dir "$HOME/Forensics/outputs" --no-daemon

Copyable request:

Read src/volatility_mcp/resources/REPORT_SPEC.md and prompts/GENERATE_REPORT.md. Investigate ~/Forensics/cases/example.vmem using the existing volatility MCP server. Create a new timestamped case bundle under ~/Forensics/outputs/reports with all required deliverables. Discover plugins, follow evidence-supported pivots, preserve exact outputs and failures, and distinguish observations, inference, and unknowns.

The companion supplies an editable Workbench template, an explicitly synthetic example, and a structural provenance check:

.venv/bin/python -m volatility_mcp report-check examples/synthetic-case

Required deliverables are report.md, case-manifest.json, investigation.jsonl, iocs.csv, and artifacts/. Hunting content is conditional. Markdown is canonical; the Workbench supplies safe browser viewing and optional per-image decorative coins. Polished standalone HTML, PDF, and DOCX exports remain deferred. The core server never assembles a report itself. The reporting workflow adds no runtime dependencies and is not loaded during ordinary tool interactions.

Reports link findings and contextualized IOCs to stable artifact IDs and useful locators, retain failures and limitations, and separate observations from inference and unknowns. The checker validates artifact paths/hashes, run ownership, required structure, and references. Supported structured citations also validate declared typed observable values against actual source rows/fields or byte ranges. Legacy locators remain readable without acquiring value-verified status. Free-form claims and analytical conclusions still require review; see the saved-evidence contract. Changes to sealed bundles belong in a new revision, not an overwrite.

Optional Workbench application

The local browser application is maintained independently in volatility-workbench. Its installer brings in a tested, pinned core dependency. Standalone MCP installs remain independent of Workbench and model providers. See the shared API and separation record.

Configuration and troubleshooting

For clone/publication connectivity or conflicting GitHub authentication errors, use the GitHub access checks. Test actual API and Git operations before treating a restricted session's DNS/auth-status error as an invalid credential.

config.local.json is private and ignored by Git. Setup records absolute Volatility interpreter/executable paths and evidence/output roots. Keep evidence, outputs, and symbol caches outside the clone. See ARCHITECTURE.md for configuration fields, execution metadata, and boundaries.

• No images listed: use an accepted extension under the evidence root. Derived outputs, symlinks, AppleDouble files, and archive metadata are excluded.

• Interpreter/plugin import failure: run doctor; verify the configured interpreter and executable belong to the same working Volatility environment. Install missing official analysis dependencies there, not into the server venv.

• Unknown argument: inspect list_plugins for the exact plugin. Global flags, custom plugin directories, traversal, shell syntax, and output overrides are rejected.

• Missing symbols or unsupported kernel: retain stderr and the failed run. Supply matching official symbols through local configuration; do not substitute an unrelated profile. A failed scan is never a clean result.

• Timeout or interrupted run: consult case_history and saved metadata before retrying. Partial output is not complete analysis. Tune the local command timeout and the client's longer tool timeout for the image size.

• Large output: use artifact references and read_output in bounded chunks. Full raw output stays on disk; response previews explicitly indicate truncation.

• MCP protocol error: run doctor --mcp; stdout must contain only MCP messages. Diagnostics belong on stderr. A stale client process may still use old code.

For guided local installation, use prompts/SETUP.md. Development instructions are in CONTRIBUTING.md; implemented capabilities and future work are separated in ROADMAP.md.

Saved results can be filtered, counted, grouped and cited with the core query_output and get_evidence tools. Workbench follow-ups use saved evidence first; its report viewer can resolve checked citations to source values. Historical locators remain readable but are not promoted to value-verified citations. See the saved-evidence contract.

Coverage is available in Workbench's Coverage tab and through get_coverage. Existing cases remain scope-unspecified unless a plan is explicitly declared; new report revisions package coverage and state its limitations. The offline synthetic evaluation command is:

.venv/bin/python tests/evaluation/run.py --output /tmp/volatility-evaluation

See coverage and evaluation for plans, state definitions, fixtures, supported versus unsupported tasks, and interpreting the result counters.