wdmcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wdmcp create a 2000x1500 map with a large landmass and three coastal towns"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
wdmcp
Python stdio MCP server for reading and writing Wonderdraft 1.1.8 .wonderdraft_map files.
Install
py -3.12 -m venv .venv # Python >= 3.12
.venv\Scripts\pip install -e .[dev]
.venv\Scripts\python -m pytest # unit tests, no Wonderdraft GUI neededRelated MCP server: fmg-mcp
Register with Claude Code
claude mcp add wonderdraft -- C:\path\to\Wonderdraft-MCP\.venv\Scripts\wdmcp.exeThe server speaks MCP over stdio (logs go to stderr). python tools/mcp_smoke.py launches it
and drives a short tool flow as a self-check.
Environment variables
Variable | Default | Meaning |
|
| Wonderdraft's resource pack (built-in symbols, themes, names) |
|
| User asset packs |
Tools
All coordinates are map pixels with the origin at the top left. Mutating tools return
{"ids": [...], "summary": "..."}. Symbol ids (symbol:<n>) are positional and shift when
symbols are inserted or removed; use the ids a tool returns, or list_objects.
Map:
new_map,open_map(read-only),save_map(timestamped.bakwhen overwriting),map_summary,undo(20 steps)Discovery:
list_themes,list_asset_sets,list_objectsTerrain:
paint_land,generate_landmass,raise_area,add_lake,add_river,paint_groundPlacement:
add_symbol,scatter_symbols,add_mountain_range,add_forest,add_settlement,add_label,add_path,add_territoryEditing:
update_object,move_objects,remove_objects,apply_theme,set_frameOutput:
render_previewreturns a PNG image and saves it (<map>.preview.pngnext to a saved map, otherwise in a temp dir);export_imagewrites a PNG/JPG file (see Export)
Points are [[x, y], ...]; colours are [r, g, b] / [r, g, b, a] floats 0-1 or "#rrggbb".
Export
export_image(path, format="png"|"jpg", via="wonderdraft"|"preview") never overwrites an
existing file.
via="wonderdraft"(default) drives the real Wonderdraft app (Windows only) for a pixel-exact export: it launches Wonderdraft with the saved map, sends Ctrl+E and Enter, fills in the save dialog, then closes Wonderdraft. It takes about 15-20 seconds. Do not type while it runs: it sends Ctrl+E/Enter to the foreground window. Wonderdraft must not already be running, and the map must be saved with no unsaved edits (callsave_mapfirst). JPG is a PNG export converted with Pillow (quality 92). If automation is unavailable or fails, the tool returns instructions (open the map, press Ctrl+E). SetWDMCP_EXEif Wonderdraft is not atC:\Program Files\Wonderdraft\Wonderdraft.exe.via="preview"writes a full-scale render from this server's own renderer; it works anywhere and needs no saved map.
Available Tools
32 toolsadd_forestB
Fill a polygon with trees from a tree set (land only). density is trees per 100x100 px of area.
Inputs: density (required), polygon (required), set_key (required), seed.
add_labelC
Add a text label using one of the theme's label presets (Town, City, Region, ...; preset_used says which one matched). color is "#rrggbb" or [r, g, b(, a)] floats 0-1 (0-255 values are rejected with a hint). size is the font size in px (default from the preset); rotation is in degrees, clockwise (90 = vertical); curve is Wonderdraft's label curve value stored as-is (0 = straight; non-zero bends the text along an arc, the sign picks the direction; start small and check in Wonderdraft, the preview draws it straight).
Inputs: pos (required), text (required), size, color, +3 more.
add_lakeB
Add a freshwater lake inside a polygon (only shows on land).
Inputs: polygon (required), seed, roughness.
add_mountain_rangeB
Place mountains in a ribbon of the given width (px) along a polyline (land only). density is symbols per 100x100 px of ribbon area.
Inputs: width (required), density (required), set_key (required), polyline (required), +1 more.
add_pathB
Add a road/path along points; points outside the map are clamped to its edge (clamped = how many). style is one of Wonderdraft's path textures: path_blended, path_circle, path_dash, path_dash_dot, path_dash_dot_dot, path_directional, path_double_paired, path_hash_marks, path_solid, path_solid_outlined. width in px; roughness is the wobble (0 = smooth, ~0.3 default).
Inputs: points (required), seed, color, style, +2 more.
add_riverA
Add a meandering river through points (first point is the source; end it in the sea or a lake); drawn on land only. width is in px at full width; the river narrows towards its source over its first few widths.
Inputs: points (required), seed, width.
add_settlementB
Place a settlement symbol and (optionally) its name label just below it. Returns [symbol_id, label_id]. Each kind has a curated default sprite (seed picks among its variants); set_key overrides the set and variant picks one sprite by index. scale multiplies the kind's default size.
Inputs: pos (required), kind (required), name (required), seed, +4 more.
add_symbolA
Place one symbol from a set (key from list_asset_sets) at pos [x, y]. variant picks a sprite by index, otherwise it is random. scale multiplies the set's base size (1 = the size Wonderdraft places it at). rotation is in degrees, clockwise.
Inputs: pos (required), set_key (required), seed, scale, +3 more.
add_territoryB
Add a filled, bordered territory polygon; points outside the map are clamped (clamped = how many). color is "#rrggbb" or [r, g, b(, a)] floats 0-1 (0-255 values are rejected with a hint). opacity is the fill opacity 0-1. style is one of Wonderdraft's border textures: border_dark_dot, border_dash, border_gradient, border_solid. width is the border width in px.
Inputs: color (required), points (required), style, width, +2 more.
apply_themeB
Apply a built-in theme (colours, textures, label presets) to the open map.
Inputs: name (required).
build_regionA
Build a complete first-draft map from a RegionSpec (see region_spec_schema), save it to out_path and make it the open map, so the edit tools and render_preview work next. Order: land, mountains, rivers/lakes, ground, forests, settlements, roads, realms, labels. A settlement on water is moved to land within 60 px (see warnings).
Inputs: spec (required), out_path (required).
export_imageA
Export the open map as an image file at path (never overwrites an existing file; a .png/.jpg suffix must match format, and is added if missing). via="wonderdraft" drives the real Wonderdraft app (Windows only) and takes about 15-20 s: close Wonderdraft first and do not type meanwhile. It needs the map saved with no unsaved edits. If automation is unavailable or fails, nothing is written and the result has via="instructions" with manual steps (open the map, press Ctrl+E) in the summary. via="preview" writes a full-scale render from this server instead.
Inputs: path (required), via, format.
generate_landmassB
Replace the whole map's terrain with generated land; coverage is the land fraction (0-1).
Inputs: kind, seed, coverage.
list_asset_setsB
List symbol sets: key (pass to add_symbol etc.), name, category (symbols|mountains|trees), pack and variant count. query matches key or name.
Inputs: limit, query, category.
list_objectsC
List objects of one kind, optionally inside bbox [x0, y0, x1, y1] (map pixels).
Inputs: kind (required), bbox, limit.
list_themesA
Names of the built-in themes usable with new_map / apply_theme.
Inputs: no named parameters.
map_summaryC
Size, theme, object counts, land fraction, included packs, file path and unsaved flag.
Inputs: no named parameters.
move_objectsB
Shift objects by (dx, dy) map pixels. Symbols/labels move their position; paths and territories move every point.
Inputs: dx (required), dy (required), ids (required).
new_mapA
Create a blank all-water map (replacing any open map; undo brings that one back) and apply a theme.
Use list_themes for theme names. Then paint land with generate_landmass or paint_land.
Inputs: theme, width, height.
open_mapA
Open a .wonderdraft_map file. The file is only read, never modified; save_map writes. The previously open map is replaced (undo brings it back).
Inputs: path (required).
paint_groundC
Paint theme ground colour number color_index (0-based) over a polygon, feathered by softness 0-1.
Inputs: polygon (required), color_index (required), softness.
paint_landA
Paint (add) or erase (subtract) land inside a polygon [[x, y], ...] with a natural, noise-displaced coastline. roughness 0 gives straight edges.
Inputs: polygon (required), mode, seed, roughness.
raise_areaB
Raise (or lower, if negative) land height inside a polygon. amount is in land-height units: land height runs from 0 (sea level) to 1 (highest), so 0.1 raises by a tenth of the full range; results are clamped to 0-1. Water is untouched and never becomes land.
Inputs: amount (required), polygon (required).
recolor_symbolsA
Repair symbols placed by older versions of this server (or by hand-edited files) so Wonderdraft draws them like its own: black-and-white "paintable" (sample_color) sprites get the land colour under them as their tint (only where it is missing, or for all of them with overwrite=true), and entries still holding the old wrong default radius 50 / offset (0, 0) get their sprite's own values. ids limits it to some symbols (default all). New placements never need this. Undoable.
Inputs: ids, overwrite.
region_spec_schemaA
JSON Schema of the RegionSpec that build_region takes (field meanings included).
Inputs: no named parameters.
remove_objectsB
Delete objects. All ids refer to the state before the call; later ids of the same kind shift down afterwards, so re-list before further edits.
Inputs: ids (required).
render_previewA
Render the map to a PNG you can see (also saved to disk; the path is in the text). scale is output px per map px (the output is capped at 8192 px on its longest side). bbox [x0, y0, x1, y1] in map pixels zooms in; show_ids tags objects with their ids.
Inputs: bbox, scale, show_ids.
save_mapA
Save the open map. Without a path, overwrite the file it was opened from. New maps need a path. Before an existing file is overwritten a timestamped .bak copy is made, at most once per file per session and never of a file this server wrote itself. Returns the absolute path and the backup (or null).
Inputs: path.
scatter_symbolsA
Scatter symbols (Poisson-disk) inside a polygon. density is symbols per 100x100 px of area (min_spacing in px, default from the set's radius, may lower the count). scale multiplies the set's base size. Returns the placed ids and how many samples were dropped (off-map, or on water with land_only).
Inputs: density (required), polygon (required), set_key (required), seed, +3 more.
set_frameB
Turn the decorative map frame on/off; texture and size are optional. texture is one of Wonderdraft's frames: celtic_dotted, celtic_leaves, celtic_woven_1, celtic_woven_2, checkered_opaque, checkered_transparent, double_pen_opaque, double_pen_transparent, double_pen_vignette, entwined_corner_opaque, entwined_corner_transparent, hatch_opaque, hatch_transparent, old_ink_opaque, old_ink_transparent, solid_line_opaque, solid_line_tansparent (sic).
Inputs: enabled (required), size, texture.
undoA
Undo the last change (up to 20 steps). After new_map, open_map or build_region, undo first brings back the map that was open before (with its own undo history).
Inputs: no named parameters.
update_objectA
Update fields of one object (id like "label:3", see list_objects). Values are checked against the type Wonderdraft stores for each key; unknown keys are rejected with the valid list.
rotation: degrees, clockwise, for symbols and labels alike (symbols are stored in radians).
scale (symbols): a number or [x, y], a multiplier on the set's base size, the same meaning as add_symbol's scale (list_objects shows the current multiplier).
variant (symbols): sprite index within the symbol's set (or within the set given as texture in the same call); texture: a sprite path. Packs are registered as needed.
style (paths/territories): a path or border texture name as in add_path / add_territory.
Vectors (position, offset) are [x, y]; colours are [r, g, b(, a)] floats 0-1 or "#rrggbb"; points (path/territory) are [[x, y], ...].
Inputs: id (required), fields (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools map to a distinct Wonderdraft primitive (paint_land, add_river, add_label, add_path), and descriptions clearly separate the terrain tools (paint_land vs generate_landmass vs raise_area) and the placement tools (add_symbol vs scatter_symbols vs add_forest). The main overlaps are render_preview vs export_image (whose "preview" mode duplicates it) and map_summary vs list_objects, plus the niche recolor_symbols repair tool, but none are likely to cause a serious misselection.
Overwhelmingly consistent snake_case verb_noun pattern (open_map, add_lake, move_objects, remove_objects, list_themes, set_frame). Minor deviations: new_map is adjective_noun rather than verb_noun, and map_summary, region_spec_schema and undo are bare nouns/verbs, but the conventions remain readable and predictable.
32 tools is heavy for an agent to navigate and sits above the comfortable range, partly inflated by meta-tools like region_spec_schema and recolor_symbols. Still, the breadth roughly tracks a genuinely rich domain (terrain, water, symbols, paths, territories, labels, themes, frames, export), so most tools earn their place.
Lifecycle coverage is strong: open/new/save/export, summary, terrain and water generation, all major object types with add/update/move/remove, theming, framing, undo, and even a one-shot build_region convenience. Minor gaps: no redo, no object duplication/copy, no get-by-id lookup beyond list_objects, and undo is capped at 20 steps.
Maintenance
Related MCP Connectors
Remote MCP server for D&D: read and update your CharGen campaigns, generate NPCs and art.
MCP server for generating rough-draft project plans from natural-language prompts.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
A remote MCP server to convert HTML documents (URL or raw source) to PDF or screenshots
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server that drives Azgaar's Fantasy Map Generator in a real browser via Playwright, enabling map generation, inspection, and exporting screenshots/SVG/JSON through natural language.1-
- FlicenseNot gradedqualityDmaintenanceMCP server that drives Azgaar's Fantasy Map Generator in a real browser via Playwright, letting users generate maps, inspect them, and export screenshots/SVG/JSON through natural language.-
- FlicenseNot gradedqualityDmaintenanceMCP server for procedural material generation and inspection via a deterministic Texture DSL, exposing tools to list, validate, render, and multiscale-inspect materials.-
- FlicenseBqualityBmaintenanceThis server enables MCP clients to inspect and edit the currently open map in the Wulfram Forge desktop editor, including moving mirrored structures, shaping terrain, capturing views, validating placements, exporting copies, and undoing changes.10-