DOSBox-X MCP Server

AI-assisted debugging of DOS binaries via the Model Context Protocol (MCP).

This MCP server enables Claude to programmatically debug DOS programs running in DOSBox-X by providing tools for:

• Setting breakpoints
• Reading/writing registers and memory
• Stepping through code
• Tracing execution

Primary Use Case

Reverse engineering classic DOS programs - specifically, tracing the unpublished Bezier curve algorithm in RIPTERM.EXE for the RIPscrip graphics protocol research project.

Quick Start

Prerequisites

• Python 3.11+
• uv package manager
• Docker (for DOSBox-X container)
• X11 display (for DOSBox GUI)

Installation

# Clone the repository
git clone https://github.com/yourusername/dosbox-mcp.git
cd dosbox-mcp

# Install dependencies
uv sync

# Build Docker image
make build

# Create DOS directory
make init

Running

# Allow X11 access for Docker
xhost +local:docker

# Start DOSBox-X
make up

# Register MCP server with Claude Code
make register

Usage with Claude

Once registered, Claude can use these tools:

# Launch DOSBox-X with a binary
launch("/path/to/GAME.EXE")

# Connect to debugger
attach("localhost", 1234)

# Set a breakpoint
breakpoint_set("1234:0100")

# Run until breakpoint
continue_execution()

# Read registers
registers()

# Read memory
memory_read("DS:0100", 64)

# Step through code
step(10)

# Clean up
quit()

Tools Reference

Execution Control

Tool	Description
launch	Start DOSBox-X with optional binary
attach	Connect to GDB stub
continue_execution	Run until breakpoint
step	Step N instructions
step_over	Step over CALL instructions
quit	Stop DOSBox-X

Breakpoints

Tool	Description
breakpoint_set	Set breakpoint at address
breakpoint_list	List all breakpoints
breakpoint_delete	Remove breakpoint(s)

Inspection

Tool	Description
registers	Read all CPU registers
memory_read	Read memory region
memory_write	Write to memory
disassemble	Simple disassembly view
stack	Dump stack contents
status	Get debugger status

Address Formats

The server supports multiple address formats:

• Segment:offset: 1234:5678 (standard DOS format)
• Flat hex: 0x12345 or 12345h
• Decimal: #65536
• Register-based: DS:SI, CS:IP

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│  DOSBox-X MCP    │────▶│   DOSBox-X      │
│                 │ MCP │  Server          │ GDB │   (GDB stub)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                              │
                              ▼
                        ┌──────────────────┐
                        │  GDB Remote      │
                        │  Protocol        │
                        │  (TCP :1234)     │
                        └──────────────────┘

Development

# Run tests
make test

# Lint code
make lint

# Format code
make format

# View logs
make logs

Project Structure

dosbox-mcp/
├── src/dosbox_mcp/
│   ├── server.py       # FastMCP server (tools)
│   ├── gdb_client.py   # GDB protocol client
│   ├── dosbox.py       # DOSBox-X management
│   ├── types.py        # Type definitions
│   └── utils.py        # Utilities
├── tests/
├── examples/
├── Dockerfile          # DOSBox-X with GDB
└── docker-compose.yml

Technical Details

GDB Remote Protocol

This server implements a client for the GDB Remote Serial Protocol, which provides:

• Register read/write (g, G, p, P)
• Memory read/write (m, M)
• Software breakpoints (Z0, z0)
• Execution control (c, s, ?)

Real Mode Addressing

DOS uses real mode with segment:offset addressing:

Physical Address = (Segment << 4) + Offset

This gives a 20-bit address space (1MB), though only 640KB is conventional memory.

Related Projects

• RIPscrip Research - Parent project for RIPscrip graphics protocol
• dosbox-x-gdb - DOSBox-X fork with GDB support
• FastMCP - MCP server framework

License

MIT License