windbg-mcp: pybag Windows 디버거 기능을 MCP 도구로 제공하는 서버

모든 pybag Windows 디버거 함수를 네이티브 MCP (Model Context Protocol) 도구로 노출하는 MCP (Model Context Protocol) 서버입니다. 이 서버는 모든 MCP 호환 클라이언트 (Claude Desktop, Claude Code, Cowork, OpenAI Codex CLI, Cursor 및 커스텀 에이전트)에 구조화된 JSON 응답을 포함한 타입 지정 도구 호출 (typed tool calls)을 통해 사용자 모드 프로세스 (user-mode processes), 커널 세션 (kernel sessions) 및 크래시 덤프 분석 (crash dump analysis)에 대한 완전한 제어권을 부여합니다.

Windows 전용 — pybag은 Microsoft Debugging Tools for Windows가 필요합니다. - Python 3.10+

• Microsoft Debugging Tools for Windows (Windows SDK의 일부)

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

pip install pybag mcp

Windows SDK를 다운로드하고 설치 중에 Debugging Tools for Windows를 선택하십시오:

서버는 로컬 stdio 프로세스로 실행됩니다. 아래의 모든 클라이언트는 다음과 같은 방식으로 서버를 실행합니다 —
python <path-to>/windbg_mcp.py

— 하지만 각 클라이언트는 고유한 설정 형식을 가집니다.

Claude Desktop 설정 파일을 편집하고 windbg-mcp 항목을 추가하십시오:

설정 파일 위치:

• Windows:
  %APPDATA%\Claude\claude_desktop_config.json

• macOS:
  ~/Library/Application Support/Claude/claude_desktop_config.json

{
"mcpServers": {
"windbg-mcp": {
...

Claude Desktop을 재시작하십시오. 55개의 디버거 도구가 자동으로 나타납니다.

서버를 등록하려면 다음 명령을 한 번 실행하십시오. Claude Code는 자체 MCP 설정에 항목을 저장하며, 이후 모든 세션에서 도구를 사용할 수 있도록 합니다.

claude mcp add windbg-mcp python C:\path\to\windbg-mcp\windbg_mcp.py

서버가 등록되었는지 확인하려면:

claude mcp list

나중에 제거하려면:

claude mcp remove windbg-mcp

Cowork에 WinDbg MCP를 추가하는 방법에는 두 가지가 있습니다: JSON 설정을 통한 방법 (빠름) 또는 .mcpb 플러그인 번들로 설치하는 방법 (휴대 가능, 공유 가능).

• Claude desktop 앱을 열고 Settings → MCP Servers로 이동합니다. - Add Server를 클릭하고 다음을 붙여넣습니다:

{
"windbg-mcp": {
"command": "python",
...

• 저장하고 Cowork를 재시작합니다. 도구는 다음 세션부터 사용할 수 있습니다.

.mcpb

.mcpb 파일은 Cowork가 직접 설치할 수 있는 플러그인 디렉토리의 zip 아카이브(zip archive)입니다. 이는 팀원과 서버를 공유하거나 여러 기기 간에 공유할 때 권장되는 방식입니다.

1단계 — .mcpb 파일 빌드하기

클론(cloned)된 저장소의 루트(root)에서 다음 명령어를 실행합니다:

powershell -Command "Compress-Archive -Path '.\*' -DestinationPath 'windbg-mcp.zip'; Rename-Item 'windbg-mcp.zip' 'windbg-mcp.mcpb'"

이를 통해 현재 디렉토리에 windbg_mcp.py, manifest.json 및 기타 프로젝트 파일들을 하나로 묶은 windbg-mcp.mcpb 파일이 생성됩니다.

2단계 — Cowork에 설치하기

• Claude 데스크톱 앱을 엽니다.
• Settings → Plugins(또는 Extensions)로 이동합니다.
• Install Plugin을 클릭하고 windbg-mcp.mcpb를 선택합니다.
• Cowork는 번들(bundle)에서 manifest.json을 읽어 MCP 서버를 등록하며, 수동 경로 설정 없이 즉시 모든 도구(tools)를 사용할 수 있게 합니다.

이 저장소에 포함된 manifest.json은 이미 올바르게 구성되어 있습니다:

{
"manifest_version": "0.2",
"name": "windbg-mcp",
...

${__dirname}은 설치 시점에 Cowork가 번들을 압축 해제한 디렉토리로 해결(resolved)되므로, 경로를 하드코딩(hard-code)할 필요가 없습니다.

서버를 Codex CLI 설정 파일에 추가합니다. 파일은 일반적으로 ~/.codex/config.json (Linux/macOS) 또는 %USERPROFILE%\.codex\config.json (Windows)에 위치합니다.

{
"mcpServers": {
"windbg-mcp": {
...

저장한 후, 새로운 Codex 세션을 시작합니다. WinDbg 도구들을 모델이 호출할 수 있게 됩니다.

• Cursor → Preferences → Cursor Settings를 엽니다.
• MCP 탭으로 이동합니다.
• Add new global MCP server를 클릭하고 다음 설정을 사용합니다:

{
"windbg-mcp": {
"command": "python",
...

• 저장합니다. Cursor는 다음 Composer 세션에서 서버에 연결됩니다.

~/.continue/config.json (또는 워크스페이스 레벨의 .continue/config.json)에 다음 내용을 추가합니다:

{
"experimental": {
"modelContextProtocolServers": [
...

Continue 확장을 다시 로드(Reload)합니다. 55개의 디버거 도구들이 도구 목록에 나타납니다.

자신만의 에이전트(Agent)나 자동화 파이프라인(Automation pipeline)을 구축하고 있다면, 표준 MCP stdio 전송(transport) 방식을 통해 WinDbg MCP에 연결하세요. 이 서버는 stdin/stdout을 통해 JSON-RPC 2.0 방식으로 통신합니다.

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

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
...

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

서버는 줄바꿈으로 구분된(newline-delimited) JSON-RPC 2.0 메시지를 통해 통신합니다. 프로세스의 stdin에 쓰고 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"}}}
...

도구 (Tool)	매개변수 (Parameters)	반환값 (Returns)
status	—	{connected, type, pid, bitness}
list_processes	—	[{pid, name, description}]
create	path (필수), args, initial_break	{status, pid, bitness}
attach	pid 또는 name (둘 중 하나만), initial_break	{status, pid, bitness}
kernel_attach	connect_string (필수), initial_break	{status, type, connect_string}
load_dump	path (필수)	{status, bitness, rip, symbol_at_rip}
connect	options (필수)	{status, options}
detach	—	{status}
terminate	—	{status}

** create** — 디버거 하에서 새로운 프로세스를 실행합니다. initial_break=True를 설정할 수 있습니다.

(기본값) 프로세스 엔트리 포인트 (entry point)에서 중단합니다. attach — 실행 중인 프로세스에 연결합니다. pid (정수) 또는 name (프로세스 파일명) 중 하나를 제공하십시오. 둘 다 제공해서는 안 됩니다. kernel_attach — 원격 커널 디버거 (kernel debugger)에 연결합니다. connect_string은 KD 구문을 사용합니다 (예: "net:port=55000,key=1.2.3.4"). load_dump — 사후 분석 (post-mortem analysis)을 위해 .dmp 파일을 엽니다. 크래시 주소 (crash address)와 가장 가까운 심볼 (symbol)을 즉시 반환합니다. connect — 원격 유저 모드 디버깅 (user-mode debugging)을 위해 프로세스 서버에 연결합니다. options는 DbgEng 연결 구문을 사용합니다 (예: "tcp:server=192.168.1.10,port=5555").

도구 (Tool)	매개변수 (Parameters)	반환값 (Returns)
go	timeout (ms, 기본값 30000)	{status, rip, symbol, new_captures, captures}
step_into	count (기본값 1)	{rip, instruction, symbol}
step_over	count (기본값 1)	{rip, instruction, symbol}
step_out	—	{rip, instruction, symbol}
goto	expr (필수)	{rip, symbol}
trace	count (기본값 10)	{instructions: [{rip, instruction, symbol}], count}

** go** — 실행을 재개하고 다음 디버그 이벤트 (중단점 (breakpoint), 예외 (exception), 또는 타임아웃 (timeout))가 발생할 때까지 차단 (block)합니다. 새로운 RIP와 실행 중에 수집된 모든 캡처 (captures)를 반환합니다.

** step_into** — 다음 명령어로 단계 진입 (step into)하며, 호출된 함수 내부로 들어갑니다.

** step_over** — 다음 명령어를 단계 실행 (step over)하며, 함수 호출을 단일 단계로 처리합니다.

** step_out** — 현재 함수가 반환될 때까지 실행합니다.

** goto** — 특정 심볼 (symbol) 또는 16진수 주소에 도달할 때까지 실행합니다 (예: "Kernel32!ExitProcess" 또는 "0x7fff12340000").

** trace** — N번의 단일 단계 반복 (single-step iterations)을 수행하고 방문한 각 명령어를 기록합니다.

도구	매개변수	반환값
bp	expr (필수), capture, action, oneshot, passcount	{id, expr, addr, capture}
hw_bp	addr (필수), size, access, capture, action, oneshot	{id, addr, size, access}
list_bps	—	[{id, expr, type, capture, action, ...}]
remove_bp	id (필수)	{status, id}
enable_bp	id (필수)	{status, id}
disable_bp	id (필수)	{status, id}

** bp** — 심볼(symbol) 또는 주소에 소프트웨어 (코드) 중단점 (breakpoint)을 설정합니다.

expr : 심볼 ("ntdll!NtCreateFile") 또는 16진수 주소 ("0x7ff800001234")
capture : true (기본값)일 때, 이 중단점이 발생할 때마다 레지스터, 스택, 메모리를 포함한 전체 상태를 캡처 버퍼 (capture buffer)에 자동으로 저장합니다.
action : "go" (기본값)는 캡처 후 실행을 계속하며, "break"는 실행을 중단합니다.
oneshot : 한 번 발생한 후 중단점을 제거합니다.
passcount : 해당 위치를 N번 통과한 후에만 발생합니다.

** hw_bp** — 하드웨어 / 데이터 중단점 (watchpoint)을 설정합니다.

addr : 감시할 16진수 주소
size : 바이트 단위의 감시 너비 — 1, 2, 4 또는 8 (기본값 4)
access : "e" 실행 (execute), "w" 쓰기 (write, 기본값), "r" 읽기/쓰기 (read/write)
capture, action, oneshot : bp와 동일한 의미를 가집니다.

** list_bps** — 현재 활성화된 모든 중단점을 ID, 표현식, 유형 및 설정과 함께 반환합니다.

** remove_bp / enable_bp / disable_bp** — bp 또는 hw_bp에서 반환된 id를 사용하여 중단점을 관리합니다.

capture: true (기본값)인 중단점은 발생할 때마다 디버거 스냅샷 (debugger snapshot) 전체를 자동으로 저장합니다. 스냅샷에는 모든 레지스터, 콜 스택 (call stack), RSP에서의 스택 메모리 64바이트, RIP에서의 코드 32바이트가 포함됩니다. 스냅샷은 버퍼에 누적되며 get_captures를 통해 언제든지 검색할 수 있습니다.

도구 (Tool)	매개변수 (Parameters)	반환값 (Returns)
get_captures	—	{count, captures: [{bp_id, expr, timestamp, registers, rip, symbol_at_rip, instruction, stack, context_memory}]}
clear_captures	—	{status}
capture_state	—	{timestamp, registers, rip, symbol_at_rip, instruction, disasm_5, stack_at_rsp, call_stack}

** get_captures** — 마지막 clear_captures 호출 이후 수집된 모든 캡처(capture)를 반환합니다. 각 캡처에는 다음 항목이 포함됩니다:
registers — 모든 레지스터 값을 {name: "0x..."} 형태의 16진수 문자열로 포함
rip — 캡처 순간의 명령어 포인터 (Instruction Pointer)
symbol_at_rip — RIP에서 가장 가까운 심볼 (Symbol)
instruction — RIP에 위치한 명령어의 역어셈블리 (Disassembly)
stack — 주소와 복귀 주소(return address)를 포함한 상위 10개의 콜 스택 (Call Stack) 프레임
context_memory.stack_at_rsp — RSP 위치의 64바이트를 16진수, 포맷팅된 형태 및 ASCII로 포함
context_memory.code_at_rip — RIP 위치의 32바이트를 16진수 및 포맷팅된 형태로 포함

** clear_captures** — 캡처 버퍼를 비웁니다. 새로운 실행을 시작하기 전에 유용합니다.

** capture_state** — 현재 상태에 대해 즉각적인 온디맨드(on-demand) 스냅샷을 찍습니다. 중단점(breakpoint)이 발생하기를 기다리는 대신, 이미 중단된 상태(broken in)일 때 사용하십시오.

도구 (Tool)	매개변수 (Parameters)	반환값 (Returns)
read_mem	addr (필수), size (기본값 16)	{addr, size, hex, formatted, ascii}
write_mem	addr (필수), data (필수, 16진수 문자열)	{status, addr, bytes_written}
read_ptr	addr (필수), count (기본값 1)	{addr, values: ["0x..."]}
poi	addr (필수)	{addr, value}
read_str	addr (필수), wide (기본값 false)	{addr, value, wide}
dump_mem	addr (필수), count (기본값 8)	{addr, output}
mem_info	addr (필수)	{addr, info}
mem_list	—	[region_description_strings]

** read_mem** — addr로부터 size만큼의 원시 바이트 (raw bytes)를 읽습니다. 데이터를 hex (압축된 형태), formatted (공백으로 구분된 바이트), ascii (출력 가능한 문자, 출력 불가능한 문자는 .로 표시) 형태로 반환합니다.

** write_mem** — 메모리에 바이트를 씁니다.

data

16진수 문자열입니다. 공백 및 \x 접두사는 자동으로 제거됩니다. (예: `