tiled-map-builder

✨ Features

• 🗺️ 31 MCP tools to create maps, paint tiles, generate rooms and corridors, and place doors, chests, traps, levers, stairs and spawns.

• 🏰 3 layout presets: a crypt, a castle floor and a werewolf den, each built in one call.

• 🎨 20 themes, 12 of them with bundled isometric sprites ready to use.

• 🛡️ Guard rails for agents: placing a chest on a wall, outside a room or on another object fails with a message that says how to fix it, and validate_map checks the map before export.

• 📐 Correct Tiled output: object positions follow Tiled's isometric convention, and saved files point at their sprites with relative paths, so they open directly in Tiled.

• 🧠 Agent skill and MCP prompt (map_builder): a step-by-step workflow with an ASCII sketch confirmation, theme heuristics and tactical rules.

• 🖌️ Optional sprite generation with FLUX.1-dev through Hugging Face. It is paid, opt-in, and never runs by accident.

• 🔌 Works with any MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Zed, OpenCode, and agents running NVIDIA Nemotron.

Related MCP server: material-workbench

🖼️ Preview

🧱 Tech stack

🚀 Quick start

Requirements: Node.js 20.9 or newer and git. Tiled is optional, to view and edit the maps.

git clone https://github.com/4math2379/Tiled-MCP-Server.git
cd Tiled-MCP-Server
npm install        # installs the server workspace
npm run build      # compiles tiled-mcp/src to tiled-mcp/dist
npm run smoke      # optional: 39 offline end-to-end checks

Then register the server with your MCP client. With Claude Code, from the repository folder:

claude mcp add tiled-map-builder -- node "$(pwd)/tiled-mcp/dist/index.js"

Most other clients take the same JSON block (replace the path with your absolute path):

{
  "mcpServers": {
    "tiled-map-builder": {
      "command": "node",
      "args": ["/absolute/path/to/Tiled-MCP-Server/tiled-mcp/dist/index.js"]
    }
  }
}

👉 Per-client instructions for Claude Desktop, Cursor, VS Code, Zed, OpenCode, Windsurf and the MCP Inspector are in docs/client-setup.md.

Now ask your agent:

Build a 28x18 crypt under an abandoned chapel with two skeletons in the nave, a locked chest in the north chamber and a dart trap before the deep crypt. Save it as crypt-chapel.tmj.

The map lands in maps/crypt-chapel.tmj. Open it in Tiled, or render a preview without Tiled:

npm run preview -- maps/crypt-chapel.tmj

🧭 How it works

flowchart LR
    A["AI agent<br/>(Claude, Nemotron, ...)"] -- MCP tools --> S["tiled-map-builder<br/>server"]
    S --> M[("Maps in memory<br/>ground · walls · decorations<br/>objects · spawns")]
    M --> V{"validate_map"}
    V --> F["save_to_disk<br/>maps/*.tmj"]
    V --> U["upload_to_dungeon<br/>(optional API)"]
    F --> T["Tiled editor<br/>or a game engine"]

1. create_map makes an empty map in a theme and returns a mapId.

2. Tiles are painted by role (walkable_floor, wall, hazard_primary, obstacle_decor, ...) and the theme picks the sprite.

3. Each map has three tile layers, ground, walls and decorations, and two object layers, objects (doors, chests, traps, levers, stairs) and spawns (player, enemy, NPC).

4. Coordinates are grid cells: x is the column and y the row; (0,0) is the top corner of an isometric map.

5. Maps live in server memory until you call save_to_disk or export_json.

Details, properties and importer formulas: docs/map-format.md.

🧰 Tools

Full parameters, generated from the server itself: docs/tools.md.

🎨 Themes

✅ sprites bundled in assets/ · ➖ no sprites yet: the maps are valid and Tiled shows placeholders until you generate the sprites.

More about each theme's roles and hazards: docs/themes.md.

🤖 Agent skill and prompt

skills/map-builder/SKILL.md teaches an agent the whole workflow: infer the theme, sketch the layout in ASCII and ask for confirmation, build, validate, save.

• Claude Code: copy the folder to ~/.claude/skills/map-builder/ (all projects) or .claude/skills/map-builder/ (one project), then type /map-builder crypt 28x18 ....

• Any MCP client: the server exposes the same workflow as the prompt map_builder, which takes a free-form description.

⚙️ Configuration

Nothing is required for map building. Optional settings go in tiled-mcp/.env (copy tiled-mcp/.env.example) or in the env block of your MCP client:

All variables, the .env lookup order and security notes: docs/configuration.md.

💸 Sprite generation (optional, paid)

Map building is free and offline. Generating new sprites calls FLUX.1-dev through Hugging Face Inference Providers and costs money per sprite. The tools never overwrite an existing sprite unless you pass force, and the batch script asks for --yes:

node scripts/gen-theme-set.mjs VOLCAN --dry-run   # free: shows what would be generated
node scripts/gen-theme-set.mjs VOLCAN --yes       # paid: about 10 sprites

Read docs/sprite-generation.md before you start.

🟩 Using it with NVIDIA Nemotron

The server works with any model that supports tool calling. It was built alongside agents running Nemotron 3.5 Super-VL on the NVIDIA API free tier, for example through OpenCode. The NVIDIA key belongs to your agent, not to this server. Setup: docs/nemotron.md.

🗂️ Repository layout

tiled-mcp/          MCP server (TypeScript): src/, package.json, tsconfig.json, .env.example
  src/tools/        tool groups: lifecycle, paint, procedural, layout-presets, objects, export, generation
  src/themes/       20 theme definitions and the FLUX prompt catalog
skills/map-builder/ agent skill, also served as the map_builder MCP prompt
maps/               sample .tmj maps (default output folder of save_to_disk)
assets/             isometric sprites per theme: <theme>/<role>.png
scripts/            example map scripts, preview renderer, sprite batch, docs generator, smoke test
docs/               documentation, banner and preview images

🛠️ Scripts

🤝 Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development loop and CHANGELOG.md for what changed.

📄 License

MIT. Tiled is an independent project by Thorbjørn Lindeijer. Some theme names evoke classic gothic-horror settings; this project is not affiliated with or endorsed by their rights holders.