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 automation API. This bridge connects any MCP-capable agent runtime (Claude Code and friends) 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: everything the automation API offers, as MCP tools.

Quick start

1. Install dosbox-automation and start it with the API enabled. The manual covers setup for all platforms.

2. Add the bridge to your MCP client. For Claude Code:

   claude mcp add dosbox -- uvx dosbox-mcp

   Or in a JSON MCP configuration:

   {
     "mcpServers": {
       "dosbox": { "command": "uvx", "args": ["dosbox-mcp"] }
     }
   }

   pipx install dosbox-mcp or pip install dosbox-mcp work just as well; the command is dosbox-mcp either way.

That's it. The bridge finds the running emulator, checks what it can do, and registers the matching tools. Ask your agent for bridge_status to confirm the connection.

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 and DOSBOX_API_TOKEN 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.