Windows Forensics

You run a dedicated MCP server that enables AI-assisted Windows forensics analysis. It parses EVTX event logs, analyzes registry hives, and supports remote collection, all accessible from MCP clients like Claude CLI. This server is designed to help you quickly extract, search, and correlate forensic evidence from Windows artifacts.

How to use

You interact with the Windows Forensics MCP Server through an MCP client. Start the server locally with Python, then connect using an MCP client to run the available tools for EVTX parsing, registry analysis, and remote collection. You can issue commands to list logs, search events, inspect registry keys, and remotely collect artifacts from Windows hosts. Use the built-in references to identify important Event IDs and registry areas as you investigate.

Key workflows include mounting evidence and collecting artifacts, enumerating EVTX files, obtaining statistics for a log, hunting for suspicious activity such as failed logon attempts or persistence mechanisms, and correlating findings across EVTX and registry data.

How to install

Prerequisites: you need Python 3.10 or newer and a fast Python package manager to install dependencies.

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# Ensure Python 3.10+
python3 --version

Install the MCP package in a virtual environment and enable remote collection support if you want WinRM, SSH, or SMB access.

# Clone the repository
https://github.com/x746b/winforensics-mcp.git
cd winforensics-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate
uv pip install -e .

# For remote collection support (WinRM, SSH, SMB):
uv pip install -e ".[remote]"

Verify installation by starting the server locally. The server should run without errors and can be stopped with Ctrl+C.

python -m winforensics_mcp.server
# Should start without errors (Ctrl+C to exit)

Configuration and usage notes

Add the server to your Claude MCP setup so you can invoke it from Claude CLI or other MCP clients. You have two methods.

# Method 1: Using claude mcp add (Recommended)
claude mcp add winforensics-mcp \
  --scope user \
  -- uv run --directory /path/to/winforensics-mcp python -m winforensics_mcp.server

If you prefer a manual JSON configuration, place this into your client’s config file.

{
  "mcpServers": {
    "winforensics-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/winforensics-mcp",
        "python",
        "-m",
        "winforensics_mcp.server"
      ]
    }
  }
}

Verify the MCP server is registered with Claude CLI by listing available MCP servers. You should see winforensics-mcp in the list.

Usage examples and available capabilities

This server provides tools to work with Windows artifacts. You will find utilities for EVTX and registry analysis, plus remote collection capabilities.

{
  "mcpServers": {
    "winforensics_mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/winforensics-mcp", "python", "-m", "winforensics_mcp.server"]
    }
  }
}

Troubleshooting

If you encounter module or permission errors, activate the virtual environment and ensure dependencies are installed. If registry hives are locked, consider offline collection from copied hives or using VSS-based collection via WinRM.

# Activate environment and verify dependencies
source /path/to/winforensics-mcp/.venv/bin/activate
pip list | grep -E "evtx|registry|mcp"

Development notes

Common workflows involve mounting an image, listing logs, getting overview statistics, hunting for suspicious activity, and correlating findings across log and registry data.

Available tools

evtx_list_files

List EVTX files in a directory.

evtx_get_stats

Get event counts, time range, and Event ID distribution for a log file.

evtx_search

Search EVTX with filters such as time, Event ID, and keywords.

evtx_security_search

Run pre-built security-related searches on EVTX data.

evtx_explain_event_id

Explain the meaning and source of a specific Event ID.

registry_get_key

Retrieve a specific registry key and its values.

registry_search

Search registry values by a pattern.

registry_get_persistence

Identify Run keys and services that indicate persistence.

registry_get_users

List user accounts from the SAM hive.

registry_get_usb_history

Extract USB device history from registry hives.

registry_get_system_info

Get OS version, hostname, and timezone from registry data.

registry_get_network

Fetch network configuration from registry hives.

forensics_list_important_events

List important Event IDs by channel.

forensics_list_registry_keys

List forensic registry keys by category.

remote_collect_artifacts

Collect artifacts from a remote Windows host via WinRM, using password or pass-the-hash.

remote_get_system_info

Retrieve remote system information.