DOSBox-X MCP Server
Minimal MCP server for controlling the DOSBox-X built-in debugger from an agent through MCP tools.
Architecture and tool details are in docs/ARCHITECTURE.md.
Build
cargo build --release
OpenCode
Download dosbox-x-mcp-server from the
GitHub Releases
section, then add it to opencode.json.
Add this to opencode.json in your project root or to your global OpenCode
config:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"dosbox": {
"type": "local",
"command": [
"<path>/dosbox-x-mcp-server"
]
}
}
}
}
For development, you can run through Cargo instead:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"dosbox": {
"type": "local",
"command": [
"cargo",
"run",
"--quiet",
"--manifest-path",
"<path>/dosbox-x-mcp-server/Cargo.toml"
]
}
}
}
}
OpenCode starts the MCP server over stdio. The MCP server first tries to listen
for native DOSBox-X on TCP port 127.0.0.1:58991 and for browser builds on
WebSocket port 127.0.0.1:58992. If either port is already in use, the server
chooses another free local port for that transport.
Ask the agent to call dosbox_dosbox_mcp_port to get the selected port. The
MCP tool itself is named dosbox_mcp_port; OpenCode adds the dosbox_ server
prefix from the configuration above. The tool works before DOSBox-X connects.
For a browser build, call dosbox_dosbox_mcp_websocket_port instead. Its MCP
tool name is dosbox_mcp_websocket_port.
The server writes logs to:
$HOME/.dosbox-x-mcp-server/server.log
Start DOSBox-X
Start OpenCode first so it launches the MCP server:
opencode
Then start a DOSBox-X build that includes the MCP debugger control changes:
./dosbox-x
Native DOSBox-X connects to the TCP port automatically when mcp_server uses
the value returned by dosbox_mcp_port.
For a browser build, set the following value in the [dosbox] section of its
configuration:
mcp_server=<port returned by dosbox_mcp_websocket_port>
The browser connects to ws://127.0.0.1:<port>/. The server accepts one active
DOSBox-X connection at a time across both transports.
In OpenCode, use tools such as dosbox_dosbox_ping, dosbox_debug_break,
dosbox_debug_exec, dosbox_debug_snapshot, and dosbox_debug_run.
Verify integration
You can verify integration by pasting prompt for agent