battlemap-mcp docs

An AI collaborator for your Dungeondraft maps: a local bridge that lets your AI assistant (Claude Desktop, Claude Code, Codex, OpenCode, or any other MCP client) build, inspect, and refine the map you have open, using assets you already own.

Sped up 11×; the actual build took about five minutes.

About battlemap-mcp has a short overview of the project.

1. Get started: install the mod and connect your AI app (Windows; also macOS and Linux).
2. Or install from Claude: the Claude desktop extension or the Claude Code plugin.
3. Include your asset packs: maps come out noticeably better with them.

This is a local automation layer for your own Dungeondraft map-making session. It does not generate original assets or art for you; it just drives what you already own in Dungeondraft.

Please support the people behind the work:

1. Buy and support Dungeondraft (required to use this project as intended).
2. Support artists and the community directly by purchasing asset packs you use, commissioning map pieces, and helping creators thrive.

This MCP can only drive features in your local Dungeondraft installation. It is meant to support creators, especially when you’re getting started, short on time, or want an assistant for tedious setup tasks. It can help you move faster, but it can never replace human creativity, taste, and mapmaking judgment.

Ask for a whole scene, work through an idea together, or hand off a repetitive job. These example prompts are starting points: change the setting, mood, and constraints to suit your game. For editing, open a map in Dungeondraft first and work on a copy you can experiment with.

Give the assistant a brief and let it develop the layout, terrain, furnishings, and lighting using assets available to your map.

Turn the blank map I have open into a ruined forest shrine for an ambush. Include a broken central sanctuary, an overgrown approach, two flanking routes, and cover for both sides. Use a restrained stone-and-moss palette. Inspect the available assets first, build the scene, then review a whole-map image and refine anything that looks cluttered or hard to navigate. Leave saving to me.

Use the assistant as a planning partner. It can inspect the map and available assets while you decide what belongs in the scene.

Look at my map and suggest three ways this abandoned mill could become an interesting encounter. For each, describe the story, a distinctive focal point, and how players might move through it. Suggest suitable assets I already have available. Don’t change the map yet; help me choose a direction first.

Keep control of the overall layout while getting help with a room, an outdoor area, or a finishing pass.

Furnish the empty room in the northeast as an alchemist’s workshop. Keep the walls and doors where they are. Add a main workbench, ingredient storage, and a small reading corner, leaving clear walking space between them. Match the materials and lighting of the adjacent rooms, then show me the result.

Ask for a Universal VTT (.dd2vtt) file and the assistant writes one beside your map, with walls, doors, windows and lights for Foundry, Roll20 or Arkenforge. Lost the original map but still have its export? The assistant rebuilds its walls, doors, windows and lights exactly, then rebuilds the art over the export’s image. It can also check a .dungeondraft_map someone sent you for packs you don’t have, before you open it.

I only have the Universal VTT export of this map: C:\Maps\snow-pass.dd2vtt. Rebuild it on the new map I have open. Show me what you’ll import before changing anything, pick packs I own that match the art, and compare your result with the export’s image when you’re done.

Ask for a second look at a map you’ve already made, with clear boundaries around what may change.

Review this tavern for blocked doorways, awkward furniture spacing, and clutter that makes the main route hard to read. Show me the areas you would change and explain why. Wait for my approval, then adjust only those areas, keeping the building layout and overall style intact.

Describe the placement rules once and let the assistant apply them across a larger area.

Place matching wall lights along this corridor at roughly four-tile intervals. Skip doors and intersections, use the same warm color and brightness, and leave existing lights alone. Check the result for uneven gaps and show me a screenshot.

Scatter small rocks and fallen branches along the forest edge, varying their rotation and spacing. Keep the path and clearing free, use only assets available to this map, and avoid a uniform repeated pattern.

The included art-direction and visual-review skills help the assistant plan and inspect its work. You decide which suggestions to use and when the map is finished. See known limitations for practical constraints.

casancam/Dungeondraft-MCP is a separate project by another author. It edits Dungeondraft map files while Dungeondraft is closed, makes variants of a map such as a night version, and turns Universal VTT (.dd2vtt) exports into Foundry VTT scenes. Use it for offline and batch work, and this project to build inside a running Dungeondraft. Its research into the asset pack format also helped this project search inside your packs.

battlemap-mcp is an independent, unofficial project and is not sponsored, operated, or endorsed by Megasploot or Tailwind Games, LLC. It does not include or redistribute Dungeondraft software, maps, or art assets. See Legal and attribution for details.

Source code, releases and issues are on GitHub. Release notes are in the changelog.