Troubleshooting battlemap-mcp

What you see	What to do
MCP Bridge is missing from Mods	Check that your selected mods folder directly contains battlemap-mcp-bridge, with mcp_bridge.ddmod inside. Avoid an extra folder from ZIP extraction.
Windows asks for administrator access	Put the files in your own user folder instead of Program Files. Select that mods folder in Dungeondraft.
“Not connected yet”	Enable MCP Bridge, open a map, wait for loading, and close any Dungeondraft dialogs. On Windows, start Dungeondraft normally rather than as administrator. Run the checker again.
The checker reports an older/different bridge	Use both downloads from the same release, remove duplicate bridge copies, and fully quit and reopen Dungeondraft.
The checker is ready, but the AI app cannot see Dungeondraft	Run the matching Connect file, finish any instructions it shows, then fully quit and reopen your AI app.
Connect says Claude Code already has a connection	An earlier install is still registered, and Connect does not replace it on its own. Open PowerShell (Terminal on a Mac), run the claude mcp remove command the window shows, then run Connect again.
Connect says it kept existing skills	Skills from an earlier install differ from this version and may hold your own edits, so Connect leaves them in place. To update them, run the command the window shows; your copies are backed up first.
Windows warns about the download or the Connect file	The Windows companion is unsigned, so Windows may warn about it. See platform limits. Choose More info → Run anyway only for files from this project’s Releases page; do not disable Windows security.
Every map tool appears twice	Two ways of connecting are active, for example the plugin or extension and a Connect registration. Keep one. To drop the Connect one in Claude Code, run claude mcp remove --scope user battlemap, then restart Claude Code.
Windows: the companion says it cannot load battlemap-mcp.pkg	The folder is incomplete. Extract the whole companion ZIP again and keep battlemap-mcp.exe, battlemap-mcp.pkg and _internal together.
The assistant keeps using the same few objects	The map probably includes no asset packs. See Include your asset packs.
You asked to see the map but no picture appeared	The assistant does see it, but your AI app folds images inside the tool call — expand the tool call to view it. The assistant is also given the saved file’s location, so you can ask it for the file.
macOS blocks the companion	Not a crash. If this is the first launch, make sure the Mac is online so macOS can confirm the notarization with Apple, then open it again. From Finder a block is a “cannot be verified” dialog; from Terminal it is only Killed: 9 and exit code 137, with no message. See macOS install, step 6.

See also: Update, move, or uninstall.

For detailed technical output, run the companion with doctor --live. It checks both installed files and the authenticated running script. A ZIP installation does not need an installer record. The loaded root identifies which copy is running when there are duplicates.

The bridge stores credentials and captures in its own private runtime directory. It does not change permissions on Dungeondraft’s folders. See privacy for what your AI client can receive. For startup problems, read the current Dungeondraft.log; timestamped logs may be archives of an earlier session.