Get started with battlemap-mcp

You need Dungeondraft 1.2.0.1 and an AI app that can run local MCP servers, on the same computer. There are three ways to connect your AI app. Pick one: with two of them, your assistant sees every tool twice.

• The companion download, for Codex, Claude Code, OpenCode and other MCP apps: follow steps 1 to 5 below. Codex, Claude Code and OpenCode connect with one double-click; other apps need a one-time manual setup (other clients).
• The Claude desktop app: install the extension. See Install from Claude.
• Claude Code: install the plugin. See Install from Claude.

Every way needs the mod in Dungeondraft, as in step 2.

Follow the Windows instructions below, or choose macOS or Linux.

Open Releases, expand Assets, and download these two files from the same release:

Download	What it does
battlemap-mcp-mod-<version>.zip	Adds MCP Bridge to Dungeondraft.
battlemap-mcp-companion-<version>-windows-x64.zip	Connects your AI app to the mod.

Skip the Source code downloads. You do not need them. Installing from Claude instead? Download only the mod ZIP and see Install from Claude.

1. Right-click the mod ZIP and choose Extract All.
2. Move the extracted battlemap-mcp-bridge folder into your usual Dungeondraft mods folder. If you do not have one, open File Explorer, enter %USERPROFILE% in its address bar, and create a folder called Dungeondraft Mods there. Use that folder instead of Program Files.
3. Open Dungeondraft and click Mods, then Browse. Select your mods folder — the folder containing battlemap-mcp-bridge, not the bridge folder itself.
4. Tick Battlemap MCP Bridge and click Accept. Then fully quit and reopen Dungeondraft: it reads mods only when it starts. Create or open a map and wait for it to finish loading. The bridge does not run on the start screen.

If you are replacing an older bridge, save your map and fully quit Dungeondraft first, then delete the old bridge folder before copying in the new one. This applies on every platform. Keep only one MCP Bridge in your active mods folders. Two bridge folders is an unsupported state, and the editor may load both or either one. Other mods can stay where they are.

1. Right-click the companion ZIP and choose Extract All.
2. Move the whole extracted battlemap-mcp folder somewhere permanent. For example, open %USERPROFILE% in File Explorer, create an Apps folder, and put it there. Keep every file inside it, including battlemap-mcp.pkg and _internal.
3. Open that folder and double-click Connect Codex, Connect Claude Code or Connect OpenCode, depending on which app you use. These files end in .cmd; Windows may hide the extension. They connect the app and add the included map-making skills. With OpenCode 1, Connect OpenCode instead shows you one entry to paste into its settings (see OpenCode).
4. Look for Setup complete, then close the window. Fully quit and reopen your AI app so it picks up the connection. If the window says Claude Code already has a connection instead, an earlier install is still registered: see If something does not work.

Do not run files while they are still inside the ZIP. Do not double-click battlemap-mcp.exe itself; your AI app starts it when needed.

If Connect Codex says automatic connection is unavailable, you can finish in the app without installing another tool: open Settings → MCP servers → Add server, choose STDIO, name it battlemap, and paste the Command path shown by the Connect window. Leave arguments empty, save, and restart the connection. See OpenAI’s MCP setup instructions.

Connect Claude Code sets up the Claude Code coding app only. For the Claude desktop chat app, use the extension instead: see Install from Claude. See client setup help for an existing Claude Code connection, or other MCP clients.

With a map open in Dungeondraft, double-click Check connection in the companion folder. It should say Ready: connected to Battlemap MCP Bridge. Installed from Claude? There is no Check connection file; go straight to the prompt below.

Then start a new conversation in your AI app and ask:

Check the Dungeondraft connection and tell me the open map’s dimensions. Don’t change anything yet.

The checker confirms the mod connection; this first prompt confirms your AI app can use it. Keep Dungeondraft and the map open while you work.

Maps come out noticeably better when the map includes asset packs. See Include your asset packs.

• Windows: the companion is unsigned. When you first open Connect or Check connection, Windows may warn you, for example with SmartScreen’s Windows protected your PC. If you downloaded both files from this project’s Releases page, choose More info → Run anyway. To confirm a download is the published one, compare Get-FileHash <file> in PowerShell with the release’s SHA256SUMS. Do not turn off SmartScreen or other Windows security.
• macOS: the companion is signed with an Apple Developer ID and notarized by Apple. The first time it runs, macOS confirms that with Apple over the internet. If your Mac is offline at that moment, macOS can block it; connect and open it again. See macOS install.
• Linux: validated on Ubuntu 24.04 under WSL2 only. Native Linux desktops and other distributions have not been tested.