home / mcp / eventwhisper mcp server

EventWhisper MCP Server

A Windows Event Log MCP

Installation

Add the following to your MCP client configuration file.

Configuration

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

EventWhisper is a mission-focused MCP server that provides fast, scriptable access to Windows EVTX logs. It runs locally as a Python-based service and is designed for incident response, digital forensics, and threat hunting without executing host commands. You can list EVTX files in a directory and filter events by time, EventID, and keywords, with optional field projection to limit output to the data you need.

How to use

You use EventWhisper by connecting an MCP client to the local stdio server. The server exposes two primary capabilities: listing EVTX files in a directory (with optional recursion) and filtering events to search for specific records. You can apply time windows, EventID filters, and include or exclude keywords. You can also project only the fields you care about to reduce output size.

Typical workflows you’ll perform include: listing available EVTX files under a directory, then running targeted searches on a chosen file or set of files. You can combine time-bounded queries with keyword filters and field projections to quickly locate relevant events.

How to install

Prerequisites: you need Python and Poetry installed on your system. Poetry manages dependencies and executes the MCP server safely in an isolated environment.

Steps you should follow exactly in order:

# 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
poetry --version

Clone the project, install dependencies, and start the MCP server:

git clone https://github.com/hexastrike/eventwhisper
cd eventwhisper
poetry install
poetry run python -m eventwhisper.mcp.server
# (or) python -m eventwhisper.mcp.server  # if dependencies are installed globally

Configuration and running via Claude MCP client

To use EventWhisper with an MCP client like Claude Desktop, configure a stdio MCP entry that launches the MCP server from Poetry. The following setup runs the server as a local process and uses UTF-8 I/O.

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

Additional notes and tips

Open Settings → Developer in Claude Desktop to confirm EventWhisper is registered and running. When prompted, allow the tool to connect and begin listing or filtering EVTX events.

If you run into issues with large logs or slow responses, keep in mind that results are capped and scanning is bounded to maintain responsiveness. If needed, run a narrower query or adjust the input to target a smaller subset of EVTX files.

Troubleshooting

Big logs can be heavy. Use the time window and keyword filters to constrain results and improve performance.

If you download EVTX files from the Internet, unblock them before usage to avoid access restrictions.

Prefer raw Windows paths using the Windows syntax (e.g., r"C:\\Windows\\System32\\winevt\\Logs").

Development notes

EventWhisper is designed to be maintainable and testable. It uses pytest for tests and ruff for linting/formatting. You can run local checks and tests to ensure everything works before integrating with an MCP client.

Available tools

list_evtx

Lists EVTX files in a directory, with optional recursive search and directory traversal.

filter_events

Filters EVTX events by time range, EventID, and keywords, with optional field projection to return only desired fields.