WinDbg MCP

Un serveur MCP (Model Context Protocol) qui expose chaque fonction de débogueur Windows pybag en tant qu'outil MCP natif. Il donne à tout client compatible MCP (Claude Desktop, Claude Code, Cowork, OpenAI Codex CLI, Cursor et agents personnalisés) un contrôle total sur les processus en mode utilisateur, les sessions noyau et l'analyse des fichiers de vidage sur incident — le tout via des appels d'outils typés avec des réponses JSON structurées.

Configuration requise

• Windows uniquement — pybag nécessite Microsoft Debugging Tools for Windows
• Python 3.10+
• Microsoft Debugging Tools for Windows (partie du SDK Windows)

Installation

1. Cloner le dépôt```bat

git clone https://github.com/your-username/windbg-mcp.git cd windbg-mcp

### 2. Installer les dépendances Python```bat
pip install pybag mcp

3. Installer les outils de débogage Microsoft

Téléchargez le SDK Windows et sélectionnez Outils de débogage pour Windows lors de l'installation : https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/

Connexion aux IDE LLM et aux clients

Le serveur s'exécute en tant que processus stdio local. Tous les clients ci-dessous le lancent de la même manière — python <path-to>/windbg_mcp.py — mais chacun a son propre format de configuration.

Claude Desktop

Modifiez le fichier de configuration de Claude Desktop et ajoutez l'entrée windbg-mcp :

Emplacement du fichier de configuration :

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json````json { "mcpServers": { "windbg-mcp": { "command": "python", "args": ["C:\path\to\windbg-mcp\windbg_mcp.py"] } } }

Redémarrez Claude Desktop. Les 55 outils de débogage apparaîtront automatiquement.

---

### Claude Code (CLI)

Exécutez la commande suivante une fois pour enregistrer le serveur. Claude Code stocke l'entrée dans sa propre configuration MCP et rend les outils disponibles dans chaque session suivante.```bash
claude mcp add windbg-mcp python C:\path\to\windbg-mcp\windbg_mcp.py

Pour vérifier que le serveur a été enregistré :```bash claude mcp list

Pour le supprimer plus tard :```bash
claude mcp remove windbg-mcp

Claude Cowork

Il y a deux façons d'ajouter WinDbg MCP à Cowork : via une configuration JSON (rapide) ou en l'installant comme un bundle de plugin .mcpb (portable, partageable).

Option A — Configuration JSON

1. Ouvrez l'application de bureau Claude et allez dans Settings → MCP Servers.
2. Cliquez sur Add Server et collez ce qui suit :```json { "windbg-mcp": { "command": "python", "args": ["C:\path\to\windbg-mcp\windbg_mcp.py"] } }

3. Enregistrez et redémarrez Cowork. Les outils seront disponibles dans votre prochaine session.

#### Option B — Installer en tant que bundle de plugin `.mcpb`

Un fichier `.mcpb` est une archive zip du répertoire du plugin que Cowork peut installer directement. Cette approche est recommandée lorsque l'on partage le serveur avec une équipe ou entre machines.

**Étape 1 — Construire le fichier `.mcpb`**

Depuis la racine du dépôt cloné, exécutez :```bat
powershell -Command "Compress-Archive -Path '.\*' -DestinationPath 'windbg-mcp.zip'; Rename-Item 'windbg-mcp.zip' 'windbg-mcp.mcpb'"

Cela crée windbg-mcp.mcpb dans le répertoire courant, regroupant windbg_mcp.py, manifest.json et tous les autres fichiers du projet.

Étape 2 — Installation dans Cowork

1. Ouvrez l'application de bureau Claude.
2. Allez dans Paramètres → Plugins (ou Extensions).
3. Cliquez sur Installer le plugin et sélectionnez windbg-mcp.mcpb.
4. Cowork lit manifest.json du bundle, enregistre le serveur MCP et rend tous les outils immédiatement disponibles — aucune configuration manuelle de chemin requise.

Le manifest.json inclus dans ce dépôt est déjà correctement configuré :```json { "manifest_version": "0.2", "name": "windbg-mcp", "version": "1.0.0", "description": "WinDbg MCP — full Windows debugger control via MCP tools", "server": { "type": "python", "entry_point": "windbg_mcp.py", "mcp_config": { "command": "python", "args": ["${__dirname}/windbg_mcp.py"] } } }

`${__dirname}` est résolu lors de l'installation dans le répertoire où Cowork a décompressé le bundle, vous n'avez donc pas besoin de coder en dur des chemins.

---

### OpenAI Codex CLI

Ajoutez le serveur à votre fichier de configuration Codex CLI. Le fichier se trouve généralement à l'emplacement
`~/.codex/config.json` (Linux/macOS) ou `%USERPROFILE%\.codex\config.json` (Windows).```json
{
  "mcpServers": {
    "windbg-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
    }
  }
}

Une fois enregistré, démarrez une nouvelle session Codex. Les outils WinDbg seront disponibles pour que le modèle puisse les appeler.

Cursor

1. Ouvrez Cursor → Préférences → Paramètres de Cursor.
2. Accédez à l’onglet MCP.
3. Cliquez sur Ajouter un nouveau serveur MCP global et utilisez cette configuration :```json { "windbg-mcp": { "command": "python", "args": ["C:\path\to\windbg-mcp\windbg_mcp.py"] } }

4. Enregistrez. Cursor se connectera au serveur lors de sa prochaine session Composer.

---

### Continue.dev

Ajoutez ce qui suit à votre `~/.continue/config.json` (ou au `.continue/config.json` au niveau de l'espace de travail) :```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "python",
          "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
        }
      }
    ]
  }
}

Reload the Continue extension. Les 55 outils de débogage apparaîtront dans la liste des outils.

Agents personnalisés et le SDK MCP

Si vous construisez votre propre agent ou pipeline d'automatisation, connectez-vous à WinDbg MCP via le transport standard MCP stdio. Le serveur parle JSON-RPC 2.0 via stdin/stdout.

Python (utilisant le mcp SDK)```python

import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client

server_params = StdioServerParameters( command="python", args=[r"C:\path\to\windbg-mcp\windbg_mcp.py"], )

async def main(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize()

        # List all available tools
        tools = await session.list_tools()
        print([t.name for t in tools.tools])

        # Load a crash dump
        result = await session.call_tool(
            "load_dump",
            arguments={"path": r"C:\crashes\crash.dmp"},
        )
        print(result.content)

        # Read 64 bytes at RSP
        result = await session.call_tool(
            "read_mem",
            arguments={"addr": "0x00000000001FF000", "size": 64},
        )
        print(result.content)

asyncio.run(main())

#### TypeScript / Node.js (utilisant le `@modelcontextprotocol/sdk` package)```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "python",
  args: ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"],
});

const client = new Client({ name: "my-agent", version: "1.0.0" }, {});
await client.connect(transport);

// Call a tool
const result = await client.callTool({
  name: "load_dump",
  arguments: { path: "C:\\crashes\\crash.dmp" },
});
console.log(result.content);

await client.close();

LangChain / LangGraph```python

from langchain_mcp_adapters.tools import load_mcp_tools from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client

server_params = StdioServerParameters( command="python", args=[r"C:\path\to\windbg-mcp\windbg_mcp.py"], )

async def get_tools(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() return await load_mcp_tools(session)

#### JSON-RPC direct via stdio (indépendant du langage)

Le serveur communique via des messages JSON-RPC 2.0 délimités par des sauts de ligne. Vous pouvez le piloter depuis n'importe quel langage en écrivant dans stdin du processus et en lisant depuis stdout :```
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{"name":"WinDbg MCP","version":"1.0.0"}}}

→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"load_dump","arguments":{"path":"C:\\crashes\\crash.dmp"}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"status\": \"ok\", ...}"}]}}

Outils disponibles (55 au total)

Gestion des sessions

create — Lance un nouveau processus sous le débogueur. Définissez initial_break=True (par défaut) pour vous arrêter au point d'entrée du processus.

attach — S'attache à un processus en cours d'exécution. Fournissez soit pid (entier) soit name (nom du fichier du processus). Ne fournissez pas les deux.

kernel_attach — Se connecte à un débogueur noyau distant. connect_string utilise la syntaxe KD, par ex. "net:port=55000,key=1.2.3.4".

load_dump — Ouvre un fichier .dmp pour une analyse post-mortem. Retourne immédiatement l'adresse du crash et le symbole le plus proche.

connect — Se connecte à un serveur de processus pour le débogage utilisateur distant. options utilise la syntaxe de connexion DbgEng, par ex. "tcp:server=192.168.1.10,port=5555".

Contrôle d'exécution

go — Reprend l'exécution et bloque jusqu'au prochain événement de débogage (point d'arrêt, exception ou timeout). Retourne le nouveau RIP et toutes les captures collectées pendant l'exécution.

step_into — Exécute pas à pas l'instruction suivante, en suivant les appels dans les fonctions appelées.

step_over — Exécute pas à pas l'instruction suivante, en traitant les appels comme une seule étape.

step_out — S'exécute jusqu'à ce que la fonction courante retourne.

goto — S'exécute jusqu'à ce qu'un symbole spécifique ou une adresse hexadécimale soit atteint, par ex. "Kernel32!ExitProcess" ou "0x7fff12340000".

trace — Effectue N itérations pas à pas uniques et enregistre chaque instruction visitée.

Points d'arrêt

bp — Définit un point d'arrêt logiciel (code) à un symbole ou une adresse.

• expr : symbole ("ntdll!NtCreateFile") ou adresse hexadécimale ("0x7ff800001234")
• capture : quand true (par défaut), sauvegarde automatiquement l'état complet — registres, pile, mémoire — dans le tampon de capture chaque fois que ce point d'arrêt se déclenche
• action : "go" (par défaut) continue l'exécution après la capture ; "break" s'arrête
• oneshot : supprime le point d'arrêt après un seul déclenchement
• passcount : ne se déclenche qu'après N passages à cet emplacement

hw_bp — Définit un point d'arrêt matériel / de données (watchpoint).

• addr : adresse hexadécimale à surveiller
• size : largeur de la surveillance en octets — 1, 2, 4 ou 8 (défaut 4)
• access : "e" exécution, "w" écriture (par défaut), "r" lecture/écriture
• capture, action, oneshot : mêmes sémantiques que bp

list_bps — Retourne tous les points d'arrêt actifs avec leurs ID, expressions, types et réglages.

remove_bp / enable_bp / disable_bp — Gère les points d'arrêt par l'id retourné par bp ou hw_bp.

Captures d'état

Les points d'arrêt avec capture: true (par défaut) sauvegardent automatiquement un instantané complet du débogueur chaque fois qu'ils se déclenchent. L'instantané comprend tous les registres, la pile d'appels, 64 octets de pile à RSP, et 32 octets de code à RIP. Les instantanés s'accumulent dans un tampon et peuvent être récupérés à tout moment avec get_captures.

get_captures — Retourne toutes les captures collectées depuis le dernier clear_captures. Chaque capture contient :

• registers — toutes les valeurs des registres sous forme de chaînes hexadécimales {name: "0x..."}
• rip — pointeur d'instruction au moment de la capture
• symbol_at_rip — symbole le plus proche de RIP
• instruction — désassemblage de l'instruction à RIP
• stack — 10 premières trames de la pile d'appels avec adresses et adresses de retour
• context_memory.stack_at_rsp — 64 octets à RSP sous forme hexadécimale, formatée et ASCII
• context_memory.code_at_rip — 32 octets à RIP sous forme hexadécimale et formatée

clear_captures — Vide le tampon de capture. Utile avant de commencer une nouvelle exécution.

capture_state — Prend un instantané immédiat à la demande de l'état actuel. Utilisez-le lorsque vous êtes déjà arrêté, plutôt que d'attendre qu'un point d'arrêt se déclenche.

Mémoire

read_mem — Lit size octets bruts à partir de addr. Retourne les données sous forme hex (compacte), formatted (octets séparés par des espaces) et ascii (caractères imprimables, . pour les non imprimables).

write_mem — Écrit des octets en mémoire. data est une chaîne hexadécimale — les espaces et les préfixes \x sont automatiquement supprimés, par ex. "90909090", "\\x90\\x90\\x90\\x90" ou "90 90 90 90".

read_ptr — Lit count valeurs consécutives de taille pointeur (4 octets en 32 bits, 8 octets en 64 bits) à partir de addr.

poi — Déréférence un pointeur unique à addr (pointeur d'intérêt).

read_str — Lit une chaîne terminée par un caractère nul. Définissez wide=true pour UTF-16LE (WCHAR Windows).

dump_mem — Vidange formatée de dword/pointeur, équivalent à dd/dp dans WinDbg.

mem_info — Retourne les propriétés de la région mémoire pour la page contenant addr : adresse de base, taille, type, état et drapeaux de protection.

mem_list — Liste toutes les régions de mémoire virtuelle dans l'espace d'adressage du processus cible.

Registres

get_regs — Retourne chaque registre disponible sous forme {name: "0x..."}. L'ensemble exact dépend de l'architecture cible (x86 vs x64).

get_reg — Retourne un registre unique, par ex. name="rax", name="eflags".

set_reg — Remplace un registre. value accepte les chaînes hexadécimales ("0x1234") ou les chaînes d'entiers décimaux.

get_pc — Retourne le pointeur d'instruction avec la résolution de symbole et le texte d'instruction décodé à cette adresse.

get_sp — Retourne la valeur actuelle du pointeur de pile.

Symboles et désassemblage

resolve — Résout un nom de symbole en son adresse virtuelle. Utilisez le format Module!Fonction, par ex. "Kernel32!WriteFile", "ntdll!NtCreateFile".

find_symbols — Recherche de symboles avec caractère générique, par ex. "ntdll!*Alloc*", "kernel32!*File*". Retourne toutes les chaînes de symboles correspondantes.

addr_to_symbol — Résolution inverse d'une adresse virtuelle vers le nom de symbole le plus proche.

disasm — Désassemble count instructions à partir de addr. Par défaut, utilise le RIP actuel si aucune adresse n'est donnée.

whereami — Retourne une description lisible du module, de la fonction et du décalage à l'adresse donnée.

Modules

list_modules — Liste tous les modules chargés dans la cible, avec leur adresse de base et leur taille.

module_info — Retourne le point d'entrée et la liste des sections (nom, adresse virtuelle, taille) pour un module spécifique, par ex. "kernel32.dll", "ntdll.dll".

get_exports — Retourne la table d'exportation complète d'un module sous forme de liste de chaînes.

get_imports — Retourne la table d'importation complète d'un module sous forme de liste de chaînes.

Threads et pile

list_threads — Liste tous les threads dans le processus cible.

get_thread — Retourne le contexte de thread actuellement actif.

set_thread — Bascule le contexte de thread actif par l'ID de thread (depuis list_threads).

get_stack — Retourne la pile d'appels sous forme de données structurées. Chaque trame comprend l'adresse de l'instruction, l'adresse de retour et le pointeur de trame.

get_teb — Retourne l'adresse du Thread Environment Block pour le thread actuel.

get_peb — Retourne l'adresse du Process Environment Block.

Processus et utilitaires

get_handles — Liste tous les handles ouverts dans le processus cible.

get_bitness — Retourne 32 ou 64 selon l'architecture cible.

raw — Exécute n'importe quelle commande WinDbg et retourne la sortie sous forme de texte. Utilisez ceci comme une échappatoire pour tout ce qui n'est pas couvert par les autres outils :``` raw(cmd="!heap -stat") raw(cmd="dt _PEB @$peb") raw(cmd="!locks") raw(cmd="lm") raw(cmd="!address @rsp")

---

## Flux de travail typiques

### Vérification d'exploit```
1. create(path="C:/target/vuln.exe", args="exploit_input.bin")
2. bp(expr="vuln!processInput+0x2A", action="break")
3. go(timeout=15000)
4. get_captures()

Dans get_captures, inspectez captures[0].registers.rip :

• "0x4141414141414141" — vous contrôlez RIP avec les octets 'A'
• Toute valeur correspondant à votre motif — contrôlée
• Une adresse qui semble valide — crash mais pas encore contrôlée

Vérifiez captures[0].context_memory.stack_at_rsp.formatted pour voir le padding, les adresses de retour ou les octets de shellcode sur la pile.

Analyse du crash dump```

1. load_dump(path="C:/crashes/crash.dmp")
2. get_regs() → full register state at crash time
3. get_stack(frames=30) → call stack at crash
4. get_sp() → read RSP value
5. read_mem(addr=, size=64) → stack contents
6. disasm() → instructions at the crash address

---

### Vérification du Heap spray```
1. attach(name="target.exe")
2. hw_bp(addr="0x1001F000", size=8, access="w", action="break")
3. go()
4. get_captures()                            → see what wrote to the spray address
5. read_mem(addr="0x1001EFC0", size=128)     → surrounding memory context

Vérification ASLR```

1. create(path="C:/target/target.exe")
2. resolve(name="kernel32!WriteFile") → record base address
3. terminate()
4. create(path="C:/target/target.exe")
5. resolve(name="kernel32!WriteFile") → compare: changed = ASLR on, same = ASLR off

---

### Débogage à distance du noyau```
1. kernel_attach(connect_string="net:port=55000,key=1.2.3.4")
2. list_modules()                        → all loaded kernel modules
3. module_info(name="ntoskrnl.exe")      → entry point and sections
4. raw(cmd="!process 0 0")              → list all processes from kernel context
5. raw(cmd="!pcr")                       → processor control region

Inspection des threads```

1. attach(pid=1234)
2. list_threads() → all thread IDs
3. set_thread(id=2) → switch context
4. get_stack(frames=20) → call stack for that thread
5. get_regs() → registers for that thread
6. get_teb() → TEB address

---

## Conseils

**Chemin des symboles** — Si la résolution des symboles ne renvoie aucun résultat, configurez le serveur de symboles Microsoft :```
raw(cmd=".sympath srv*C:\\symbols*https://msdl.microsoft.com/download/symbols")
raw(cmd=".reload")

Timeout tuning — go() par défaut à 30 secondes. Pour les cibles qui s'exécutent plus longtemps avant d'atteindre un point d'arrêt:``` go(timeout=120000) # 2 minutes go(timeout=300000) # 5 minutes

**Format d'adresse** — Tous les paramètres `addr` acceptent des chaînes hexadécimales (`"0x1234abcd"`, `"7fff12340000"`) ou des entiers simples. Le préfixe `0x` est optionnel pour les valeurs hexadécimales.

**Vérification du shellcode** — Après une capture, utilisez `read_mem` et `disasm` sur l'adresse où votre shellcode doit atterrir. Si `disasm` affiche vos instructions prévues, la charge utile est arrivée intacte.

**Après `terminate` ou `detach`** — Toutes les captures et points d'arrêt sont effacés automatiquement. Appelez `create` ou `attach` pour démarrer une nouvelle session.

**`capture_state` vs `get_captures`** — Utilisez `capture_state` pour un instantané à la demande lorsque vous êtes déjà arrêté à un point d'arrêt. Utilisez `get_captures` pour récupérer l'état qui a été automatiquement sauvegardé à chaque déclenchement d'un point d'arrêt lors d'un appel `go`.

**Commandes `raw` du noyau** — Extensions de débogage du noyau courantes qui fonctionnent bien via `raw` :```
raw(cmd="!process 0 0")       → list all processes
raw(cmd="!thread")            → current thread details
raw(cmd="!irql")              → current IRQL
raw(cmd="!pcr")               → processor control region
raw(cmd="!pte <addr>")        → page table entry for an address
raw(cmd="dt nt!_EPROCESS @$proc")  → dump EPROCESS structure

Licence

MIT