WinDbg MCP

Um servidor MCP (Model Context Protocol) que expõe cada função do depurador Windows pybag como uma ferramenta MCP nativa. Ele concede a qualquer cliente compatível com MCP (Claude Desktop, Claude Code, Cowork, OpenAI Codex CLI, Cursor e agentes personalizados) controle total sobre processos em modo de usuário, sessões de kernel e análise de dumps de falha — tudo por meio de chamadas de ferramentas tipadas com respostas JSON estruturadas.

---

Requisitos

• Apenas Windows — pybag requer Microsoft Debugging Tools for Windows
• Python 3.10+
• Microsoft Debugging Tools for Windows (parte do Windows SDK)

---

Instalação

1. Clone o repositório```bat

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

### 2. Instalar dependências Python```bat
pip install pybag mcp

3. Install Microsoft Debugging Tools

Baixe o Windows SDK e selecione Debugging Tools for Windows durante a instalação: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/

---

Conectando-se a IDEs e Clientes de LLM

O servidor é executado como um processo stdio local. Todos os clientes abaixo o iniciam da mesma forma — python <path-to>/windbg_mcp.py — mas cada um tem seu próprio formato de configuração.

---

Claude Desktop

Edite o arquivo de configuração do Claude Desktop e adicione a entrada windbg-mcp:

Local do arquivo de configuração:

• 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"] } } }

Reinicie o Claude Desktop. Todas as 55 ferramentas de depuração aparecerão automaticamente.

---

### Claude Code (CLI)

Execute o seguinte comando uma vez para registrar o servidor. O Claude Code armazena a entrada
em sua própria configuração MCP e disponibiliza as ferramentas em cada sessão subsequente.```bash
claude mcp add windbg-mcp python C:\path\to\windbg-mcp\windbg_mcp.py

Para verificar se o servidor foi registrado:```bash claude mcp list

Para removê-lo mais tarde:```bash
claude mcp remove windbg-mcp

---

Claude Cowork

Existem duas formas de adicionar o WinDbg MCP ao Cowork: através da configuração JSON (rápida) ou instalando-o como um pacote de plugin .mcpb (portátil, compartilhável).

Opção A — Configuração JSON

1. Abra o aplicativo de desktop Claude e vá para Configurações → Servidores MCP.
2. Clique em Adicionar Servidor e cole o seguinte:```json { "windbg-mcp": { "command": "python", "args": ["C:\path\to\windbg-mcp\windbg_mcp.py"] } }

3. Salve e reinicie o Cowork. As ferramentas estarão disponíveis na sua próxima sessão.

#### Opção B — Instalar como um Pacote de Plugin `.mcpb`

Um arquivo `.mcpb` é um arquivo zip do diretório do plugin que o Cowork pode instalar diretamente. Esta é a abordagem recomendada ao compartilhar o servidor com uma equipe ou entre máquinas.

**Passo 1 — Construir o arquivo `.mcpb`**

A partir da raiz do repositório clonado, execute:```bat
powershell -Command "Compress-Archive -Path '.\*' -DestinationPath 'windbg-mcp.zip'; Rename-Item 'windbg-mcp.zip' 'windbg-mcp.mcpb'"

Isto cria windbg-mcp.mcpb no diretório atual, agrupando windbg_mcp.py, manifest.json e quaisquer outros arquivos do projeto.

Passo 2 — Instalar no Cowork

1. Abra o aplicativo de desktop Claude.
2. Vá para Configurações → Plugins (ou Extensões).
3. Clique em Instalar Plugin e selecione windbg-mcp.mcpb.
4. O Cowork lê manifest.json do pacote, registra o servidor MCP e disponibiliza todas as ferramentas imediatamente — sem necessidade de configuração manual de caminho.

O manifest.json incluído neste repositório já está configurado corretamente:```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}` é resolvido no momento da instalação para o diretório onde o Cowork descompactou o pacote, então você não precisa codificar caminhos de forma fixa.

---

### OpenAI Codex CLI

Adicione o servidor ao seu arquivo de configuração do Codex CLI. O arquivo geralmente está localizado em `~/.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"]
    }
  }
}

Após salvar, inicie uma nova sessão do Codex. As ferramentas WinDbg estarão disponíveis para o modelo chamar.

---

Cursor

1. Abra Cursor → Preferências → Configurações do Cursor.
2. Navegue para a aba MCP.
3. Clique em Adicionar novo servidor MCP global e use esta configuração:

{
  "mcpServers": {
    "windsurf": {
      "type": "stdio",
      "command": "windsurf",
      "args": ["mcp"]
    }
  }
}
``````json
{
  "windbg-mcp": {
    "command": "python",
    "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
  }
}

4. Salvar. O Cursor se conectará ao servidor na sua próxima sessão do Composer.

---

Continue.dev

Adicione o seguinte ao seu ~/.continue/config.json (ou ao nível do espaço de trabalho .continue/config.json):```json { "experimental": { "modelContextProtocolServers": [ { "transport": { "type": "stdio", "command": "python", "args": ["C:\path\to\windbg-mcp\windbg_mcp.py"] } } ] } }

Recarregue a extensão Continue. As 55 ferramentas do depurador aparecerão na lista de ferramentas.

---

### Agentes Personalizados e o SDK MCP

Se você está construindo seu próprio agente ou pipeline de automação, conecte-se ao WinDbg MCP
através do transporte stdio padrão do MCP. O servidor fala JSON-RPC 2.0 via stdin/stdout.

#### Python (usando o SDK `mcp`)```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 (usando o pacote @modelcontextprotocol/sdk)```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