Install on macOS

The macOS companion is signed with an Apple Developer ID and notarized by Apple. Verified on Apple Silicon; the Intel companion has been checked only under Rosetta on Apple Silicon, not on an Intel Mac.

The first time the companion runs, macOS confirms its notarization with Apple over the internet. If your Mac is offline at that moment, macOS can block it; connect and open it again. Step 6 describes what a block looks like.

From the same release, download battlemap-mcp-mod-<version>.zip and your Mac companion: macos-arm64.tar.gz for Apple Silicon, or macos-x64.tar.gz for Intel. Apple menu → About This Mac shows your chip; in Terminal, uname -m prints arm64 or x86_64. Skip the Source code archives.

The release also carries SHA256SUMS, a .whl and battlemap-mcp-<version>.mcpb. You do not need the .whl: it is for running from Python packaging instead of the companion, and is covered in developer installation. The .mcpb is the Claude desktop extension, an alternative to the companion (see Install from Claude). To check your downloads, run shasum -a 256 -c SHA256SUMS in the download folder; every listed file should say OK.
Extract the mod ZIP — double-click it in Finder, or run unzip battlemap-mcp-mod-<version>.zip in Terminal. Move the battlemap-mcp-bridge folder into the mods folder Dungeondraft is pointed at. If you have never chosen one, create Dungeondraft Mods in your home folder and select it in step 3.

Replacing an older bridge: save your map and fully quit Dungeondraft first. Then move the old bridge folder out of the mods folder — anywhere outside it will do, and moving it aside is safer than deleting if you may want it back. Copy the new one in afterwards. Two bridge folders in one mods folder is an unsupported state, and the editor may load both or either of them.

The old bridge may be a symbolic link rather than a real folder, which is normal if it was installed from a source checkout. Move or remove the link itself; the checkout it points at is not affected. Take out only the bridge entry, not the whole mods folder, if anything else lives there.

Quarantine on the extracted mod files is harmless and needs no action. Dungeondraft reads them; the shell never executes them, so the block that affects the companion does not apply here.
In Dungeondraft choose Mods → Browse, select the folder that contains the bridge folder, tick Battlemap MCP Bridge, and click Accept. Then fully quit and reopen Dungeondraft — it reads mod source once at launch, so a newly enabled mod is not running until you restart. Create or open a map afterwards: the bridge does not start until a map is open.
Extract the companion archive — double-click it in Finder, or run tar -xzf battlemap-mcp-companion-<version>-macos-arm64.tar.gz. Move the whole battlemap-mcp folder somewhere permanent in your home folder, such as ~/Apps/battlemap-mcp. Keep _internal and every other file alongside the executable.
Open Connect Codex.command, Connect Claude Code.command or Connect OpenCode.command. These install the bundled skills and register the companion with that client (with OpenCode 1, Connect OpenCode prints an entry for you to paste instead; see OpenCode).
If macOS blocks it. On the signed companion, make sure the Mac is online and open it again; that is usually all it takes, and you do not need the quarantine command below. An unsigned build, such as one you built yourself, is blocked every time until you allow it. What you see depends on how you started it:
- From Finder: a dialog saying the developer cannot be verified. Open System Settings → Privacy & Security, scroll to Security, and click Open Anyway next to the blocked item.
- From Terminal: no dialog and no message at all — just Killed: 9 and exit code 137. That is the same block, reported silently. It is not a crash and not a fault in the package.
If you choose to run an unsigned build anyway, clear the download quarantine on the folder from step 4:
Terminal window
```
xattr -d -r com.apple.quarantine ~/Apps/battlemap-mcp
```
That marks one folder as something you decided to trust. It does not turn off Gatekeeper and changes nothing else on your Mac. If you would rather not, stop here and say so.

If an AI assistant is doing the install for you, it may be refused at this point: agents commonly run behind a permission layer that blocks clearing quarantine, and sometimes blocks launching an unsigned binary even after it is cleared. That is the agent’s sandbox, not macOS and not this package. Run the command yourself in Terminal and let the assistant carry on, or use a signed build, where none of this arises.
Open Check connection.command with a map open in Dungeondraft. Expect Ready: connected to Battlemap MCP Bridge. If it says the connection was refused instead, the map is probably still loading: wait until it is fully open and run the check again.

Then restart your AI client, because a newly registered server only loads in a new session. In a terminal client, exit it and start it again. In a desktop app, quit it completely (⌘Q, not just closing the window), reopen it, and start a new conversation.

If you check the companion with spctl -a -t exec -vv, a signed build still reports rejected (the code is valid but does not seem to be an app). That is spctl declining to judge a command-line tool as an application, not Gatekeeper blocking it — the line below it naming Developer ID Application is the part that matters, and the companion runs normally.

If you prefer Terminal, from the companion folder:

./battlemap-mcp setup --client codex
./battlemap-mcp doctor --live --brief

Use claude-code or opencode instead of codex for those clients. On an unsigned build, or on a first launch without a network, both commands hit the step 6 block first.