dosbox-mcp

MCP server for dosbox-automation: drive a DOS machine from an AI agent.

dosbox-automation is a DOSBox fork with a built-in REST API for automation. This bridge connects any MCP-capable agent (Claude Code, Claude Desktop, or anything that speaks the Model Context Protocol) to a running emulator. The agent can type into DOS programs, read the screen, capture frames and video, run sandboxed Lua scripts, and inspect memory.

Getting started

You need the emulator, this bridge, and an MCP client such as Claude Code or Claude Desktop. The bridge runs on Python 3.11 or newer.

1. Get dosbox-automation

Download from the releases page or build from source. Linux and Windows builds are on the releases page; on macOS you build from source. The manual has the platform-specific setup.

2. Enable the API

Open the primary config file. It lives at ~/.config/dosbox-automation/dosbox-automation.conf on Linux, %LOCALAPPDATA%\dosbox-automation\ on Windows and ~/Library/Preferences/dosbox-automation/ on macOS. In its [webserver] section (add the section if the file has none), set:

[webserver]
webserver_enabled = true
webserver_token_file = true
mount_allowed_bases = /home/you/dos

The last line names the folder your DOS programs live in. The emulator refuses to mount anything outside the folders listed there, so without it the agent can type MOUNT all day and get nothing. On Windows write the path as C:\Users\you\dos.

Start dosbox-automation. The DOS prompt appears in its window. To check the API is up, open http://localhost:8386/ in a browser: the API's documentation page answers.

3. Install the bridge

Pick one:

pipx install dosbox-mcp

uvx dosbox-mcp

pip install dosbox-mcp inside a virtual environment works too, but then the dosbox-mcp command lives in that environment's bin folder, and step 4 needs its full path.

You never start the bridge by hand. Your MCP client launches it when a conversation begins and stops it afterwards. Run in a terminal, it waits silently for a client that never comes.

4. Register with your MCP client

Claude Code, available in every project directory:

claude mcp add --scope user dosbox -- dosbox-mcp

With uvx instead of an install:

claude mcp add --scope user dosbox -- uvx dosbox-mcp

Claude Desktop: open Settings, then Developer, then Edit Config, and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "dosbox": { "command": "/home/you/.local/bin/dosbox-mcp" }
  }
}

Use the full path (which dosbox-mcp, or where dosbox-mcp on Windows): a desktop app does not see your shell's PATH. For uvx, use "command": "uvx", "args": ["dosbox-mcp"]. Restart Claude Desktop afterwards; it reads the file only at start.

The bridge reads the emulator's API token from ~/.config/dosbox-automation/webserver/api_token. On Windows and macOS the emulator writes the token under its own config folder from step 2, in a webserver subfolder; point the bridge at that file with the DOSBOX_TOKEN_FILE environment variable or the token_file setting (see Configuration).

5. Hello world

Start a new conversation with your agent and ask it something like:

Type DIR in the DOS prompt and tell me what files you see.

The agent calls the bridge tools to type the command, reads the screen text, and reports back what DOS printed. From here you can mount the folders you listed in step 2, run and install programs, capture screenshots, search memory for values, or write Lua scripts that automate entire workflows. The bridge_status tool confirms the connection if you want to check first.

Configuration

Optional. Write a commented config file to tune the port, spawn an emulator on demand, or limit what an agent may do:

dosbox-mcp setup --init

The comments in the generated file explain each setting. Environment variables DOSBOX_API_URL, DOSBOX_API_TOKEN and DOSBOX_TOKEN_FILE override it. The bridge talks to loopback addresses only; it will not reach out to a remote machine.

What the agent gets

Tools for session control, screen text and captures, video recording, Lua scripting, keyboard and mouse input, and memory access. You choose how much reach an agent has, from read-only observation to full control.

An open protocol

The contract between this bridge and the emulator is written down in PROTOCOL.md and versioned independently. dosbox-automation is the reference implementation; any DOSBox variant that speaks the protocol works with this bridge.

In the box

Like the games it drives, this one ships with its paper. The feelies/ folder holds the manual, a reference card for every tool, an install sheet, and a tech-support page.

Requirements

• Python 3.11 or newer
• A running dosbox-automation (0.84-da2 or newer) on the same machine

License

GPL-2.0-or-later. See LICENSE. The protocol specification (PROTOCOL.md) is licensed CC-BY-SA-4.0.

---

This project is developed with tooled assistance, but tested, reviewed and signed off by a human developer.