# GameWorld Painter MCP [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/aleserb/game-world-painter  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1000  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/game-world-painter-mcp

## Description
MCP server for GameWorld Painter, the layered game world map editor: AI agents (Claude Code, Codex, GitHub Copilot, VS Code, Cursor, Gemini CLI) read, analyze and edit the map open in the app.

## Tools
Capabilities this server exposes over MCP:

- **get_map_info** — Start here. The open map: title, unit, bounds, cell size, every layer with what it holds (mask coverage, categories classes and their shares, height range, object kinds and property keys, notes, vector paths), the zones, conventions, and what the user is looking at. Coordinates: x grows east, z grows south, north is up.
- **open_map** — Opens the map in the folder at "path" (the folder with metadata.json) in GameWorld Painter. The app then reads and writes that folder through this MCP server, without the user picking it. When no app is connected, the server opens it in the default browser with a link that connects it and opens the map (the user may have to allow Chrome to reach this device). The map open before is saved first.
- **create_map** — Creates a new map in the folder at "path" (made if missing; it must not have a map yet) and opens it in the app: the bounds and cell size in the unit of the map, and a set of layers — "basic" (terrain height, ground, zones, water, roads, rivers, borders, rocks, grass, bushes, trees, buildings, enemies, chests, hiding spots, notes), "none" (no layers: make them with create_layer), "notes" (only notes), or "same" (the layers of the map open now, empty). Then shape it with the other tools.
- **get_user_context** — What the user is pointing at now: the selected area (its bounds and size), the selected items (their layer, kinds, ids), the selected layers, the active layer and tool, the view, the cursor, and what became of your latest changes. The user selects objects with Select (click, box) or the Select area tools (rectangle, ellipse, lasso, polygon, same kind) to show you what they mean. Use it for requests like "this area", "here", "these", "the selected ones".
- **get_project_path** — The full path of the project folder open in the app on this computer (the folder with metadata.json and layers/), the path of every layer file, and what the app has not saved yet. Use it to read or change the files with other tools (scripts, image tools, exporters). The browser does not reveal paths, so the server finds the folder — in your workspace, your working directory, then the home folder — and checks it is the same one (its metadata.json). If it is not found, ask the user for the path and pass it as "path".
- **render_map** — An image of the map from above (north up) with a coordinate grid: the whole map, the view, or a region. Look before and after changes. Optional highlight of a region.
- **describe_region** — Everything in a region: its size and bounds, mask coverage, categories shares (zones, ground), heights and slopes, and the items of every layer by kind. Use it to check an area before and after changing it.
- **read_layer** — The values of a mask (0–100 %), categories (class names) or height layer as a coarse grid over a region, row by row from north to south. For exact work use describe_region, find_spots or the edit tools instead of reading every cell.
- **find_items** — Items of objects, notes and vector layers with filters: region, kind, properties, distance to a point. measure adds facts per item: the distance to the nearest feature of other layers (e.g. roads, water), the height, the slope, the zone.
- **analyze_items** — How items are spread in a region: nearest-neighbor distances, pairs closer than min_distance, groups (items within cluster_distance of each other) and the largest empty gaps. Use it to check or even out placements while keeping groups.
- **find_spots** — Finds the best spots in a region by a measure of the terrain and the layers, as ranked areas with a center point. open: far from cover (open, exposed ground); enclosed: much cover around (poor view, hidden); high / low: above / below the surroundings (viewpoints, hollows); flat / steep: slope; empty: far from any item and cover (looks empty); far_from / near_to: distance to given layers.
- **analyze_walkability** — Walkable ground in a region (slope below max_slope, outside blocking layers such as water, cliffs, buildings) split into connected parts: the main part (from start, else the largest), isolated pockets where a player could get stuck or never get to, narrow passages, and items standing on blocked or isolated ground.
- **find_route** — The best walking route between two places on the terrain: not steeper than max_slope, around blocking layers, preferring some layers (roads) and keeping away from others (enemies, danger zones). Returns the route as points; add_to adds it as a path to a vector layer.
- **add_items** — Adds items to an objects, notes or vector layer. Objects: {kind, x, z, yaw?, w?, d?, props?} (zone is filled from the zones layer). Place an object one of three ways: its center x, z and yaw (degrees counter-clockwise seen from above: its length w points along (cos yaw, −sin yaw) — 0 east, 90 north, −90 south); its two ends "a": [x,z] and "b": [x,z] (center, yaw and, for footprints, the length w follow; d is its width, default 3 m) — use it for bridges, walls, fences, anything from one point to another; or x, z and "towards": [x,z] (its length points there). Notes: {x, z, text, color?}. Paths: {kind, points: [[x,z] or [x,z,width]...], closed?, width?, smooth?, props?}. Match the usual size of the kind (get_map_info → kind_sizes). The result has "checks" when something looks wrong (overlaps, water, a bridge along the river…). One undo step for the user.
- **update_items** — Changes items by id: set fields ({"id":3,"kind":"ruin"}), merge properties ({"id":3,"props":{"level":5}}, null removes one), move by an offset ({"id":3,"move":[dx,dz]}), turn ({"id":3,"turn":90}, degrees counter-clockwise), place anew by its ends ({"id":3,"a":[x,z],"b":[x,z]}) or point it ({"id":3,"towards":[x,z]}). One undo step.
- **delete_items** — Deletes items of a layer by ids, or all items matching region and kind. The app may ask the user to confirm. One undo step.
- **scatter_items** — Places many objects naturally (blue-noise spacing) in a region: weighted kinds, a minimum spacing, an optional count, a density layer, distances to keep from other layers, groups (packs of 3–5 around a center), random rotation and properties. Existing items of the layer keep the spacing too. dry_run returns the positions without adding. One undo step.
- **paint_layer** — Paints a mask (value in percent) or a categories layer (value: a class name) over a region, with a soft edge (feather) and natural variation (noise). Modes: set, max (only raise), min (only lower), add, subtract, erase. One undo step.
- **edit_terrain** — Changes the height layer in a region with a soft edge. raise / lower by amount; flatten to height (default: the mean height there); smooth with radius; slope: an even ramp from one place to another (the heights there, or given ones); noise: natural bumps of amount with scale. One undo step.
- **create_layer** — Creates a layer: mask, category (classes), height, objects (style marker or footprint), notes or vector (paths). It goes on top of its group. One undo step.
- **update_layer** — Changes the settings of a layer: name, note, group, color, visible, opacity, label, width, add or rename categories classes. The agent cannot unlock layers. One undo step.
- **show_on_map** — Moves the user's view to a region, items or a point and outlines it for a few seconds, with an optional message. select: also make it the selected area. Use it to point at what you changed or found.
- **check_change** — Shows you your open change (between begin_change and end_change, or a proposal waiting for review) before the user judges it: two images of the place — BEFORE and AFTER, with your objects outlined and labeled (#id kind; bridges with a line from end a to b; problems in red) — what changed per layer, and checks of every object placed or moved: overlaps with other objects, standing in water or on a road, uneven ground (with the flatten call), bridges (both ends on dry land, crossing the water, the angle to the flow: 90° is straight across). end_change runs the same checks and does not finish while problems are left. With "items" it checks objects already on the map. Look at the images: do they match what the user asked?
- **find_crossing** — Finds the narrowest places to cross a river or other water in a region (default: the user's selected area, else the view): for each, the two points on the banks — a and b, on dry land — for a bridge straight across the flow, its length, the width of the water, the yaw, the angle to the flow, the heights and slopes at both ends, and objects in the way. Then add_items {"kind": "<bridge>", "a": a, "b": b, "d": <width>}. Also lists the crossings already on the map (kinds and sizes).
- **begin_change** — Groups the next changing calls into one change the user sees on a card over the map with your title and description, until end_change. In review mode (get_map_info → review_mode on, the default) it is one proposal: the steps apply at once but are held until the user accepts, asks for changes or rejects it all. Without review mode it becomes one undo step. Use it whenever one idea takes more than one call (e.g. ruins + rubble + overgrowth). Without it each changing call is its own change (in review mode: its own proposal, which waits for the decision).
- **end_change** — Ends the change opened with begin_change. First it checks the objects of the change (as check_change): while problems are left (overlaps, objects in the water, a bridge along the river or with an end in the water…) the change stays open and you get the problems — fix them and call end_change again, or give "ignore_problems" with the reason. In review mode it then shows the proposal to the user and waits for the decision (up to "wait" seconds): accepted (kept and saved), changes_requested (undone; "feedback" says what the user wants instead: make a new change), rejected (undone), or pending (call wait_for_review). Without review mode the change is applied as one undo step (status done).
- **wait_for_review** — Waits for the user to decide on a proposal (up to "wait" seconds) and returns the decision: accepted, changes_requested (with "feedback"), rejected, or pending (still waiting: call again).
- **undo** — Undoes the latest changes made by the agent (only while they are the latest changes in the app). In review mode: withdraws your proposal that waits for review.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "gameworld-painter-mcp": {
    "command": "npx",
    "args": ["-y","game-world-painter-mcp"]
  }
}
```

## Documentation

## What GameWorld Painter MCP does

GameWorld Painter MCP MCP server gives AI agents an interface to a map open in the GameWorld Painter web application. GameWorld Painter is a top-down world editor whose projects are folders containing PNG and JSON data. The server lets an agent inspect that data through the app, reason about selected or named regions, and make changes that can be reviewed in the map UI.

The supported map model includes terrain height, mask and category layers, placed objects, notes, and vector features such as roads or rivers. Agents can request map overviews, grid images, regional facts, object lists with distances, open or hidden areas, walkability, routes, spacing, and groups. They can also work with regions such as a selected area, a zone, space around roads, or intersections.

## How it works

The MCP package runs locally with Node.js 18 or newer and has no dependencies according to the project documentation. An MCP-compatible client starts the server, while GameWorld Painter remains open in Chrome or Edge on the desktop. The server can open an existing map by path or create a new one; it can also open the app in the browser when needed.

Changes are presented to the agent with before-and-after images and outlined objects. GameWorld Painter can check proposed work for conditions such as overlaps, objects placed in water or on roads, uneven terrain, and bridge endpoints. Review mode is enabled by default in the app, so an agent’s edits become proposals that a user can accept, modify with a comment, or reject. Each accepted change is one undo step.

The application watches the project folder and normally reflects external changes within about a second. The folder remains the source of truth, making the map usable by build scripts, importers, notebooks, or other tools that read PNG and JSON.

## Setup and configuration

Install the package through an MCP client using the command shown in the project documentation:

```text
npx -y game-world-painter-mcp
```

The repository also provides a setup command that prints configuration commands for supported agents:

```text
npx -y game-world-painter-mcp setup
```

Open GameWorld Painter at its hosted web address in Chrome or Edge, create or open a project folder, and enable the AI Agent control in the app header. The status indicator shows when an agent is connected. The app requires the File System Access API, which Firefox and Safari do not provide for this workflow.

## Tools and capabilities

GameWorld Painter MCP MCP server supports agent operations for:

- Reading map overviews, rendered images, measurements, regional facts, objects, routes, walkability, spacing, and groups.
- Finding suitable locations and crossings, including bridge crossings with land at both ends.
- Scattering objects, adding or editing items, deleting items, and creating layers.
- Painting masks and categories with soft edges or noise.
- Raising, lowering, flattening, smoothing, and sloping terrain.
- Getting the project path for scripts and other file-based workflows.
- Opening maps or creating new maps from a filesystem path.

The agent can act on the current selection or on meaningful map regions. Object edits include properties and placement, while the app’s underlying files preserve terrain, layer, object, vector, and note data.

## Limitations and notes

The tool operates on the map open in GameWorld Painter rather than providing a standalone game-engine editor. The browser application must be run on a compatible desktop browser, and its file access permission must be granted for the project folder. The 3D preview uses WebGL2 when available and falls back to a simpler software view when it is not.

GameWorld Painter MCP MCP server is intended for the 🎮 Gaming category and is most relevant when an agent needs spatial context, visual review, or batch changes across a layered game-world plan.

_Full upstream README: https://allmcps.com/mcp/game-world-painter-mcp/readme_