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.

1. Check your chip: Apple menu → About This Mac shows it; in Terminal, uname -m prints arm64 or x86_64.

2. 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. Skip the Source code archives.

3. To check your downloads, run shasum -a 256 -c SHA256SUMS in the download folder; every listed file should say OK.

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. The .mcpb is the Claude desktop extension, an alternative to the companion (see Install from Claude).

1. 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 the next step.

2. In Dungeondraft choose Mods → Browse, select the folder that contains the bridge folder, tick Battlemap MCP Bridge, and click Accept.

3. 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.

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.

1. 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.

2. Open Connect Codex.command, Connect Claude Code.command or Connect OpenCode.command. These install the bundled skills and register the companion with that client; Connect OpenCode prints an entry for you to paste instead (see OpenCode).

3. 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.

1. 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.

2. In a new conversation, ask your AI app to check the Dungeondraft connection and tell you the open map’s dimensions, without changing anything yet.

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 block described below first.

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.

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 companion folder:

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.