Skip to main content
Glama

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 needed

Related MCP server: fmg-mcp

Register with Claude Code

claude mcp add wonderdraft -- C:\path\to\Wonderdraft-MCP\.venv\Scripts\wdmcp.exe

The 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

WDMCP_PCK

C:\Program Files\Wonderdraft\Wonderdraft.pck

Wonderdraft's resource pack (built-in symbols, themes, names)

WDMCP_USER_DIR

%APPDATA%\Wonderdraft\assets

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 .bak when overwriting), map_summary, undo (20 steps)

  • Discovery: list_themes, list_asset_sets, list_objects

  • Terrain: paint_land, generate_landmass, raise_area, add_lake, add_river, paint_ground

  • Placement: add_symbol, scatter_symbols, add_mountain_range, add_forest, add_settlement, add_label, add_path, add_territory

  • Editing: update_object, move_objects, remove_objects, apply_theme, set_frame

  • Output: render_preview returns a PNG image and saves it (<map>.preview.png next to a saved map, otherwise in a temp dir); export_image writes 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 (call save_map first). 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). Set WDMCP_EXE if Wonderdraft is not at C:\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 tools
add_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

    B3.4/5.0

    Scored across 32 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP 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
      -
    • F
      license
      B
      quality
      B
      maintenance
      This 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
      -