# battlemap-mcp

> battlemap-mcp is an open-source MCP server for games and play. Drive Dungeondraft from an AI assistant to build and edit battle maps with your assets. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** Windows, macOS, Linux
- **Website:** https://knownframe.com/battlemap-mcp/
- **Repository:** https://github.com/thekannen/battlemap-mcp
- **MCP Registry name:** io.github.thekannen/battlemap-mcp
- **Categories:** games and play, design and media
- **Listing updated:** 2026-11-14

## About

Map-making in Dungeondraft can be tedious at scale, and this bridge lets an AI client place rooms, terrain, furniture and lighting in the map you already have open. It does not generate art. It only uses assets installed in your Dungeondraft, and the README asks users to support the artists behind them.

The setup has a Dungeondraft mod and a companion program from the same release; the companion connects your MCP client to the mod over a local connection. Dungeondraft 1.2.0.1 and a client that runs local MCP servers on the same computer are required. It also detects some community mods, such as Unofficial Patch, Custom Snap Mod, Soft Shadows and Sketch Tool, and adapts, for instance by reading a hex grid or keeping sketch notes out of exports.

Tasks include building a map from a brief, planning an encounter, furnishing a room, and exporting to or rebuilding from a Universal VTT file. The project states it has no accounts, telemetry or analytics, apart from an optional daily release check.

## Features

- **Uses your own assets:** Works with packs already installed in Dungeondraft.
- **Local bridge:** Mod and companion talk on your computer; no accounts or telemetry.
- **Mod awareness:** Detects Unofficial Patch, Custom Snap Mod, Soft Shadows and Sketch Tool.
- **Universal VTT:** Export to or rebuild from a Universal VTT file.
- **Several clients:** Claude Desktop, Claude Code, Codex, OpenCode or any MCP client.

## Good for

- Lay out a tavern from a written brief
- Furnish and light a single room
- Plan an encounter route on an existing map
- Hand off repetitive object placement

## Install

### Claude Code (Terminal)

```sh
claude mcp add battlemap-mcp -- npx -y https://github.com/thekannen/battlemap-mcp/releases/download/v1.4.3/battlemap-mcp-1.4.3.mcpb
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "battlemap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/thekannen/battlemap-mcp/releases/download/v1.4.3/battlemap-mcp-1.4.3.mcpb"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "battlemap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/thekannen/battlemap-mcp/releases/download/v1.4.3/battlemap-mcp-1.4.3.mcpb"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "battlemap-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/thekannen/battlemap-mcp/releases/download/v1.4.3/battlemap-mcp-1.4.3.mcpb"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "battlemap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/thekannen/battlemap-mcp/releases/download/v1.4.3/battlemap-mcp-1.4.3.mcpb"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "battlemap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/thekannen/battlemap-mcp/releases/download/v1.4.3/battlemap-mcp-1.4.3.mcpb"
      ]
    }
  }
}
```

## FAQ

### Does it create art?

No. It places assets you already own in Dungeondraft.

### What do I need?

Dungeondraft 1.2.0.1 and an AI client that runs local MCP servers on the same computer.

### What platforms?

Windows, macOS and Linux.

### What does it cost?

It is free and open source under the MIT licence; Dungeondraft is bought separately.

### Is battlemap-mcp free?

Yes. battlemap-mcp is open source, so you can use and self-host it for free.

### How do I add battlemap-mcp to Claude Code?

Run this command in your terminal: claude mcp add battlemap-mcp -- npx -y https://github.com/thekannen/battlemap-mcp/releases/download/v1.4.3/battlemap-mcp-1.4.3.mcpb

### What are the best alternatives to battlemap-mcp?

The closest alternatives to battlemap-mcp are HyperFrames by HeyGen, ffmpeg-skill, AvatarSay — Fictional Character & Talking Video MCP, ChartAnt and VfxSmith.

## Alternatives

- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [AvatarSay — Fictional Character & Talking Video MCP](https://ai-powered.com/mcp/avatarsay-fictional-character-and-talking-video-mcp): AvatarSay — Fictional Character & Talking Video MCP is a freemium MCP server for design and media.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [VfxSmith](https://ai-powered.com/mcp/vfxsmith): VfxSmith is a freemium MCP server for design and media.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.
- [Hourlore](https://ai-powered.com/mcp/hourlore): Hourlore is a freemium MCP server for design and media.
- [Eikino](https://ai-powered.com/mcp/eikino): Eikino is a freemium MCP server for security.

---
Source: https://ai-powered.com/mcp/battlemap-mcp
