Windows Forensics MCP Server

Author: xtk

A comprehensive Model Context Protocol (MCP) server for Windows digital forensics, enabling AI-assisted analysis of Windows artifacts directly from Claude CLI or any MCP-compatible client.

Features

EVTX Parsing - Windows Event Log analysis with filtering, search, and pre-built security queries
Registry Analysis - Parse SAM, SYSTEM, SOFTWARE, SECURITY, NTUSER.DAT hives
Remote Collection - Collect artifacts via WinRM with password or pass-the-hash authentication
Forensic Reference - Built-in knowledge of important Event IDs and registry keys

Installation

Prerequisites

# 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 Package

# 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

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

Adding to Claude CLI

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

Method 2: Manual JSON Configuration

Edit ~/.claude.json:

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

Verify

claude mcp list
# Should show winforensics-mcp

Tool Reference

EVTX Tools

| Tool | Description | |------|-------------| | evtx_list_files | List EVTX files in a directory | | evtx_get_stats | Get event counts, time range, Event ID distribution | | evtx_search | Search with filters (time, Event ID, keywords) | | evtx_security_search | Pre-built security event searches | | evtx_explain_event_id | Get Event ID description |

Registry Tools

| Tool | Description | |------|-------------| | registry_get_key | Get specific key and values | | registry_search | Search values by pattern | | registry_get_persistence | Get Run keys and services | | registry_get_users | Get user accounts from SAM | | registry_get_usb_history | Get USB device history | | registry_get_system_info | Get OS version, hostname, timezone | | registry_get_network | Get network configuration |

Reference Tools

| Tool | Description | |------|-------------| | forensics_list_important_events | List important Event IDs by channel | | forensics_list_registry_keys | List forensic registry keys by category |

Remote Tools

| Tool | Description | |------|-------------| | remote_collect_artifacts | Collect artifacts via WinRM (password or pass-the-hash) | | remote_get_system_info | Get remote system info |

Usage Examples with Sample Output

1. List Available Event Logs

Request:

List all EVTX files in /mnt/evidence/Windows/System32/winevt/Logs

Output:

[
  {
    "name": "Security.evtx",
    "path": "/mnt/evidence/Windows/System32/winevt/Logs/Security.evtx",
    "size_bytes": 69206016,
    "modified": "2025-03-17T20:00:00"
  },
  {
    "name": "System.evtx",
    "path": "/mnt/evidence/Windows/System32/winevt/Logs/System.evtx",
    "size_bytes": 4194304,
    "modified": "2025-03-17T19:55:00"
  }
]

2. Get Event Log Statistics

Request:

Show me stats for Security.evtx

Output:

{
  "file": "Security.evtx",
  "total_events": 15847,
  "time_range": {
    "earliest": "2025-01-15T08:00:00Z",
    "latest": "2025-03-17T19:51:24Z"
  },
  "top_event_ids": {
    "4624": 3521,
    "4625": 847,
    "4634": 3498,
    "4672": 1205,
    "4688": 4892
  }
}

3. Search for Failed Logon Attempts

Request:

Find all failed logon events in Security.evtx

Output:

{
  "event_type": "failed_logon",
  "count": 12,
  "events": [
    {
      "EventID": 4625,
      "TimeCreated": "2025-03-17T19:46:10Z",
      "TargetUserName": "svc_backup",
      "TargetDomainName": "CORP",
      "LogonType": 3,
      "Status": "0xC000006D",
      "SubStatus": "0xC000006A",
      "WorkstationName": "WKS001",
      "IpAddress": "192.168.1.50",
      "ProcessName": "C:\\Windows\\Temp\\RunasCs.exe"
    },
    {
      "EventID": 4625,
      "TimeCreated": "2025-03-17T19:46:14Z",
      "TargetUserName": "admin_ops",
      "TargetDomainName": "CORP",
      "LogonType": 3,
      "Status": "0xC000006D",
      "ProcessName": "C:\\Windows\\Temp\\RunasCs.exe"
    }
  ]
}

4. Analyze User Accounts from SAM

Request:

List all user accounts from the SAM hive

Output:

{
  "users": [
    {
      "username": "Administrator",
      "rid": 500,
      "created": "2024-08-21T08:27:42Z",
      "last_login": "2025-03-17T19:44:14Z",
      "login_count": 42,
      "password_last_set": "2025-03-17T19:51:23Z",
      "account_flags": ["Password Never Expires"]
    },
    {
      "username": "Guest",
      "rid": 501,
      "created": "2024-08-21T08:27:42Z",
      "last_login": null,
      "login_count": 0,
      "account_flags": ["Account Disabled"]
    },
    {
      "username": "svc_deploy",
      "rid": 1002,
      "created": "2025-03-17T19:47:02Z",
      "last_login": "2025-03-17T19:51:24Z",
      "login_count": 1,
      "account_flags": []
    }
  ]
}

5. Check Persistence Mechanisms

Request:

Check for persistence in the SOFTWARE and SYSTEM registry hives

Output:

{
  "run_keys": [
    {
      "key": "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run",
      "name": "SecurityHealth",
      "value": "%ProgramFiles%\\Windows Defender\\MSASCuiL.exe",
      "suspicious": false
    },
    {
      "key": "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run",
      "name": "VMware User Process",
      "value": "\"C:\\Program Files\\VMware\\VMware Tools\\vmtoolsd.exe\" -n vmusr",
      "suspicious": false
    }
  ],
  "services": [
    {
      "name": "WinDefend",
      "display_name": "Windows Defender Antivirus Service",
      "image_path": "\"C:\\ProgramData\\Microsoft\\Windows Defender\\platform\\4.18.2302.7-0\\MsMpEng.exe\"",
      "start_type": 2,
      "suspicious": false
    }
  ],
  "suspicious_count": 0
}

6. Get System Information

Request:

What Windows version and computer name from the registry?

Output:

{
  "computer_name": "WKS001",
  "domain": "corp.local",
  "os": {
    "product_name": "Windows 10 Pro",
    "build": "19041",
    "version": "2004",
    "install_date": "2024-08-21T08:25:00Z"
  },
  "timezone": "Pacific Standard Time",
  "last_shutdown": "2025-03-17T06:00:00Z"
}

7. Get Network Configuration

Request:

Show network configuration from SYSTEM hive

Output:

{
  "interfaces": [
    {
      "name": "Ethernet0",
      "dhcp_enabled": false,
      "ip_address": "192.168.1.50",
      "subnet_mask": "255.255.255.0",
      "default_gateway": "192.168.1.1",
      "dns_servers": ["192.168.1.10", "192.168.1.11"]
    }
  ]
}

8. Search Registry for Suspicious Entries

Request:

Search the SOFTWARE hive for 'mimikatz'

Output:

{
  "pattern": "mimikatz",
  "matches": [],
  "count": 0
}

9. Get USB Device History

Request:

Show USB device history from SYSTEM hive

Output:

{
  "devices": [
    {
      "vendor": "SanDisk",
      "product": "Ultra USB 3.0",
      "serial": "4C530001234567890",
      "first_connected": "2025-02-10T14:30:00Z",
      "last_connected": "2025-03-15T09:00:00Z"
    }
  ]
}

10. Remote Artifact Collection

Request with Password:

Collect forensic artifacts from 192.168.1.100 with username 'admin' and save to /cases/case001

Request with Pass-the-Hash:

Collect artifacts from 192.168.1.100 as administrator using hash aad3b435b51404ee:31d6cfe0d16ae931b73c59d7e0c089c0

Output:

[
  {
    "artifact": "Security.evtx",
    "success": true,
    "local_path": "/cases/case001/evtx/Security.evtx",
    "size_bytes": 69206016,
    "error": null
  },
  {
    "artifact": "SAM",
    "success": true,
    "local_path": "/cases/case001/registry/SAM",
    "size_bytes": 65536,
    "error": null
  },
  {
    "artifact": "SYSTEM",
    "success": true,
    "local_path": "/cases/case001/registry/SYSTEM",
    "size_bytes": 17825792,
    "error": null
  }
]

Important Event IDs Reference

Security Log

| Event ID | Description | |----------|-------------| | 4624 | Successful Logon | | 4625 | Failed Logon | | 4672 | Special Privileges Assigned | | 4688 | Process Creation | | 4697 | Service Installed | | 4698-4702 | Scheduled Task Events | | 4720 | User Account Created | | 1102 | Audit Log Cleared |

System Log

| Event ID | Description | |----------|-------------| | 7045 | New Service Installed | | 7036 | Service Started/Stopped | | 104 | Event Log Cleared |

Sysmon

| Event ID | Description | |----------|-------------| | 1 | Process Creation | | 3 | Network Connection | | 11 | File Created | | 12-14 | Registry Events | | 22 | DNS Query |

Typical Investigation Workflow

1. Mount or Collect Evidence

# Mount Windows image
mount -o ro /dev/sdb1 /mnt/evidence

# Or collect from remote system
"Collect artifacts from 192.168.1.50 user admin to /cases/incident001"

2. Discover Available Logs

"List all EVTX files in /mnt/evidence/Windows/System32/winevt/Logs"

3. Get Overview

"Show stats for Security.evtx - what events are most common?"

4. Hunt for Suspicious Activity

"Find all failed logon attempts in Security.evtx"
"Search for process creation events with powershell or cmd"
"Look for service installations in System.evtx"

5. Analyze Registry

"Check persistence mechanisms in the SOFTWARE and SYSTEM hives"
"Get user account details from SAM"
"Search registry for references to suspicious IP 10.10.10.10"

6. Correlate Findings

"Show me events between 2025-01-15T10:00:00Z and 2025-01-15T12:00:00Z"

Troubleshooting

"Module not found" errors

source /path/to/winforensics-mcp/.venv/bin/activate
pip list | grep -E "evtx|registry|mcp"

"Permission denied" on registry hives

Registry hives may be locked. Either:

Use offline/copied hives from a mounted image
Use VSS (Volume Shadow Copy) collection via WinRM

WinRM connection issues

# Test with password
python -c "import winrm; s=winrm.Session('http://HOST:5985/wsman', auth=('user','pass')); print(s.run_cmd('hostname'))"

# Test with pass-the-hash
python -c "import winrm; s=winrm.Session('http://HOST:5985/wsman', auth=('user','00000000000000000000000000000000:NTHASH'), transport='ntlm'); print(s.run_cmd('hostname'))"

Remove MCP Server

claude mcp remove winforensics-mcp --scope user

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .
ruff format .

License

MIT License

Credits

python-evtx - EVTX parsing
python-registry - Registry parsing
MCP - Model Context Protocol

Windows Forensics MCP Server

Features

Installation

Prerequisites

Install the Package

Verify Installation

Adding to Claude CLI

Method 1: Using claude mcp add (Recommended)

Method 2: Manual JSON Configuration

Verify

Tool Reference

EVTX Tools

Registry Tools

Reference Tools

Remote Tools

Usage Examples with Sample Output

1. List Available Event Logs

2. Get Event Log Statistics

3. Search for Failed Logon Attempts

4. Analyze User Accounts from SAM

5. Check Persistence Mechanisms

6. Get System Information

7. Get Network Configuration

8. Search Registry for Suspicious Entries

9. Get USB Device History

10. Remote Artifact Collection

Important Event IDs Reference

Security Log

System Log

Sysmon

Typical Investigation Workflow

1. Mount or Collect Evidence

2. Discover Available Logs

3. Get Overview

4. Hunt for Suspicious Activity

5. Analyze Registry

6. Correlate Findings

Troubleshooting

"Module not found" errors

"Permission denied" on registry hives

WinRM connection issues

Remove MCP Server

Development

License

Credits

Install Package (if required)

Cursor configuration (mcp.json)

Method 1: Using `claude mcp add` (Recommended)