WineDbg MCP Server

This project provides a server that wraps the Wine Debugger (winedbg) and exposes its functionality through a simple API. This allows you to debug Windows applications running under Wine from a remote client.

Installation

1. Install Wine and winedbg.

2. Create a Python virtual environment and install the required dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

Related MCP server: Aragorn

Usage

1. Start the server:

   python -m src.mcp_server

2. Run the test client to see the server in action:

   python tests/test_client.py

Testing with the Test App

This project includes a simple C application that can be used for testing the server.

1. Compile the test application for 32-bit Windows:

   i686-w64-mingw32-gcc -o tests/test_app.exe tests/test_app.c

   If you don't have the MinGW-w64 cross-compiler, you can install it on Debian/Ubuntu with: sudo apt-get install gcc-mingw-w64-i686

2. Run the test client:

   python tests/test_client.py

   The test client will automatically use the test_app.exe to test the server's functionality.

MCP Server Configuration

If you are using a client that supports launching MCP servers, you can configure it with the following JSON. This tells the client how to start the winedbg server.

Note: Make sure to replace /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-winedbg with the actual absolute path to this project directory on your system.

{
  "mcpServers": {
    "winedbg": {
      "command": "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-winedbg/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-winedbg/src/mcp_server.py"
      ]
    }
  }
}

Available Tools

The server exposes the following tools:

• run: Run an executable in winedbg.

• attach: Attach to a process.

• quit: Quit winedbg.

• detach: Detach from the process.

• kill: Kill the process.

• cont: Continue execution.

• break_at: Set a breakpoint.

• watch: Set a watchpoint.

• info_break: Get breakpoint info.

• delete_breakpoint: Delete a breakpoint.

• backtrace: Get a backtrace.

• frame: Select a stack frame.

• up: Move up the stack.

• down: Move down the stack.

• step: Step execution.

• next: Next execution.

• stepi: Step instruction.

• nexti: Next instruction.

• finish: Finish execution of the current function.

• print_var: Print a variable.

• examine_memory: Examine memory.

• info_locals: Get local variables.

• info_args: Get function arguments.

• info_proc: Get process info.

• info_threads: Get thread info.

• info_share: Get shared library info.

• set_debug_channel: Set the WINEDEBUG environment variable.

• get_debug_channels: Get the WINEDEBUG environment variable.