Eventwhisper

🚀 EventWhisper — A Windows Event Log MCP

EventWhisper provides fast and scriptable access to Windows .evtx logs through an MCP (Model Context Protocol) server. It is written in pure Python (utilizing the evtx library), rather than being a PowerShell wrapper, and does not execute commands on the host. This makes it a safer choice for incident response, digital forensics, and threat hunting.

The server offers two main tools:

• List EVTX files (optionally recursively) in any directory.
• Filter events to directly search for specific records.

It is specifically designed for IR/DFIR and hunting, eliminating the need to constantly look up Event IDs. Developed and tested on Windows with Claude, it can be used with any MCP client.

✨ Features

• Targeted filtering: Supports time window, EventID(s), and case-insensitive keywords (include/exclude).
• Field projection: Returns only the required dotted paths, significantly reducing output.
• Input normalization: Accepts flexible input formats, ensuring functionality even when types/format are not perfect.
• MCP-ready: Can be integrated with Claude Desktop (and other MCP clients).

🎥 Demo

https://github.com/user-attachments/assets/e1878c86-56f6-466b-bbc4-04d1edeeb36b

📦 Installation Requirements (Windows)

EventWhisper can be set up using Poetry, whether run inside Claude or standalone. On Windows, ensure that Poetry is added to your PATH.

Install Poetry (PowerShell):

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Add Poetry to PATH (user install):

C:\Users\<YourUser>\AppData\Roaming\Python\Scripts

Verify:

poetry --version

🚀 Install & Run

EventWhisper is mainly developed for use with Claude, but you can also run the MCP server independently and integrate it with other LLMs.

Clone and install:

git clone https://github.com/hexastrike/eventwhisper
cd eventwhisper
poetry install

Run the MCP server:

poetry run python -m eventwhisper.mcp.server
# (or) plain Python if deps are installed globally:
python -m eventwhisper.mcp.server

🛠️ Claude MCP Configuration

Add the following to Claude Desktop’s MCP config (e.g., %AppData%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "EventWhisper": {
      "type": "stdio",
      "command": "poetry",
      "args": [
        "-C",
        "C:\\Path\\To\\eventwhisper",
        "run",
        "python",
        "-m",
        "eventwhisper.mcp.server"
      ],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Open Settings → Developer to confirm that EventWhisper is registered and “running”.

When prompted, allow the tool:

Try a first prompt:

Use EventWhisper to list .evtx files in C:\Windows\System32\winevt\Logs.

💻 Usage Examples

Basic Usage

# example.py
from __future__ import annotations
from datetime import datetime, timezone
from eventwhisper.evtxio.evtxio import get_events_from_evtx

# 1) First matching event from Security log
print(get_events_from_evtx(r"C:\Windows\System32\winevt\Logs\Security.evtx", results_limit=1))

Advanced Usage

# 2) Filter by keywords and project fields
events = get_events_from_evtx(
    r"C:\Windows\System32\winevt\Logs\Security.evtx",
    contains=["powershell", "Invoke-"],
    fields=["Event.System.EventID", "Event.EventData.Image", "Event.EventData.CommandLine"],
    results_limit=5,
)
for e in events:
    print(e)

# 3) Time-bounded query (UTC)
start = datetime(2025, 1, 1, tzinfo=timezone.utc)
end = datetime(2025, 1, 31, 23, 59, 59, tzinfo=timezone.utc)
print(len(get_events_from_evtx(r"C:\Windows\System32\winevt\Logs\Security.evtx", start=start, end=end)))

Run it with poetry run python example.py.

🛠️ Development

EventWhisper is designed to be simple and maintainable. We use pytest for testing and ruff for linting/formatting. You can run all operations locally (or via pre-commit):

poetry install
poetry run ruff format .
poetry run ruff check . --fix
poetry run pytest --cov=eventwhisper --cov-report=term-missing
# pre-commit on all files:
poetry run pre-commit run --all-files
# pre-push hooks (full tests + coverage):
poetry run pre-commit run --hook-stage push --all-files

When submitting pull requests, make sure all tests pass and coverage thresholds are met. Every new utility or feature should include clear tests and follow PEP 8. Tests are located in the tests/ directory.

Core layout & API

The main logic is in eventwhisper/evtxio/evtxio.py for EVTX iteration/filtering/projection.

The core server function is get_events_from_evtx() (a wrapper around the iterator iter_events_from_evtx()):

def get_events_from_evtx(
    provider: str | Path,
    start: datetime | str | None = None,
    end: datetime | str | None = None,
    results_limit: int | str | None = RESULTS_LIMIT,
    event_ids: int | str | Sequence[int] | Sequence[str] | None = None,
    contains: str | Sequence[str] | None = None,
    not_contains: str | Sequence[str] | None = None,
    fields: str | Sequence[str] | None = None,
) -> list[str]:

Constants are defined in eventwhisper/utils/config.py, including:

• RESULTS_LIMIT — The maximum number of events returned (LLMs have token/character limits).
• SCAN_LIMIT — The maximum number of events scanned to ensure fast responses for large logs.

🐞 Troubleshooting

• Big logs: Results are limited by RESULTS_LIMIT, and scanning is restricted to keep responses fast. If your MCP client does not recognize the result limit, run a second, more targeted query.
• “Blocked” files: If you downloaded .evtx files from the Internet, right-click → Properties → Unblock.
• Paths: In Python, use raw strings for Windows paths, e.g., r"C:\path\file.evtx".
• README video: GitHub does not support <video> tags; use a thumbnail → MP4 link (see the Demo section).

🗺️ Roadmap

• Faster scanning for very large .evtx files.
• Better normalization for malformed/corrupted EVTX.
• Convenience utilities (e.g., quick overview: counts, unique EventIDs, time range).
• Optional paging / multi-query strategies for large datasets.

📄 License

This project is distributed under the GPLv3 license. See LICENSE for details.