tiled-mcp

Stripped-down MCP server for editing Tiled .tmj maps — read map structure, place/fill/replace tiles, manage tile layers, validate. TMJ-only (no TMX writes), no object/property tools, no Docker, no HTTP transport.

Install

# No install needed — run directly with npx:
claude mcp add tiled --scope user \
  -e TILED_PROJECT_DIR=/path/to/your/tiled/project \
  -- npx tiled-mcp

# Or install globally and reference the binary:
npm install -g tiled-mcp
claude mcp add tiled --scope user \
  -e TILED_PROJECT_DIR=/path/to/your/tiled/project \
  -- tiled-mcp

TILED_PROJECT_DIR is the root folder that contains your .tmj map files. All paths the MCP exposes are resolved relative to it, and any path that escapes it is rejected.

Build from source

git clone https://github.com/YOUR_USERNAME/tiled-mcp
cd tiled-mcp
npm install
npm run build

Then wire it up pointing at the local build:

claude mcp add tiled --scope user \
  -e TILED_PROJECT_DIR=/path/to/your/tiled/project \
  -- node /path/to/tiled-mcp/dist/index.js

Tools

| Tool | Description | |------|-------------| | tiled_list_maps | List all .tmj/.tmx files under TILED_PROJECT_DIR | | tiled_get_map | Read a map and return its full JSON structure | | tiled_get_map_summary | Concise summary: dimensions, layers, tileset gid ranges | | tiled_validate_map | Check data length, gid ranges, external tileset paths | | tiled_get_layer | Read a single layer's full data | | tiled_create_layer | Append a new empty tilelayer | | tiled_update_layer | Update name, visibility, opacity, offset, tint | | tiled_delete_layer | Remove a top-level layer | | tiled_get_tile_at | Get the gid at a specific (x, y) coordinate | | tiled_find_tiles | Find all coordinates where a gid appears | | tiled_place_tiles | Place one or more tiles ([{x, y, gid}]) | | tiled_fill_region | Fill a rectangular region with a single gid | | tiled_clear_region | Erase tiles (set gid=0) in a rectangular region | | tiled_replace_tiles | Replace every occurrence of one gid with another | | tiled_list_tilesets | List tileset references in a map | | tiled_get_tileset | Read an external .tsj tileset file |

All writes are atomic (temp file + rename). Reads never mutate the file.

Disclaimer

tiled-mcp is an independent project and is not affiliated with or endorsed by the Tiled map editor or its maintainers.

License

MIT