Warcraft III Map Tools README | AllMCPs

wc3-mcp

Made by GodMephisto

An MCP server that lets AI assistants such as Claude read, audit and edit Warcraft III .w3x and .w3m maps byte-faithfully (files you do not touch keep their bytes).

It is the MCP server of wc3ctl, which also has a command line tool and a desktop editor. Install wc3ctl if you want those as well. It carries the same server as wc3ctl mcp serve.

What you need

64-bit Windows. The game data reader (CascLib) is a Windows library.
Warcraft III Reforged, only for the tools that read base game data. Map tools work without it.
Any AI app that speaks MCP. Nothing else, the release carries its own .NET.

Install

Open PowerShell and run

powershell

irm https://raw.githubusercontent.com/GodMephisto/wc3-mcp/main/install.ps1 | iex

That downloads the latest release, checks its SHA-256, unpacks it into %LOCALAPPDATA%\Programs\wc3-mcp, adds that folder to your PATH and sets up every supported AI app it finds. No admin rights. Run the same line again to update. Restart your AI app afterwards.

Prefer to do it by hand? Download the zip from the Releases page, unzip it into any folder you like, then from that folder run

powershell

.\wc3-mcp.exe install --all

The setup records wherever the exe actually is, so any folder works. It also adds that folder to your user PATH once, so from then on plain wc3-mcp works in any new terminal. Pass --no-path to skip that, and use .\wc3-mcp.exe from its folder instead.

Using Claude Desktop only? Download wc3-mcp-<version>-win-x64.mcpb from the Releases page and double-click it. Claude Desktop installs it as an extension. Its one setting, the Warcraft III folder, can stay empty to have the install detected. The server is also listed in the MCP Registry as io.github.GodMephisto/wc3-mcp, for apps that install from there.

Set up your AI app

These need wc3-mcp on your PATH, which the one-line install and the first wc3-mcp.exe install both arrange. Until then, run them as .\wc3-mcp.exe ... from the folder the exe is in.

Code

wc3-mcp install --all            set up every supported app found on this PC
wc3-mcp install cursor vscode    set up only the apps named
wc3-mcp uninstall --all          remove it again
wc3-mcp config <app>             print the settings to paste by hand
wc3-mcp clients                  list supported apps and whether each is set up
wc3-mcp doctor                   check the install, the game folder and the apps

App	Name to use	Where it is written
Claude Code	`claude-code`	through `claude mcp add --scope user`
Claude Desktop	`claude-desktop`	`%APPDATA%\Claude\claude_desktop_config.json` (Store build too)
Cursor	`cursor`	`%USERPROFILE%\.cursor\mcp.json`
VS Code (GitHub Copilot)	`vscode`	`%APPDATA%\Code\User\mcp.json`
Windsurf	`windsurf`	`%USERPROFILE%\.codeium\windsurf\mcp_config.json` or `%APPDATA%\devin\mcp_config.json`
Gemini CLI	`gemini`	`%USERPROFILE%\.gemini\settings.json`
Codex CLI	`codex`	`%CODEX_HOME%` or `%USERPROFILE%\.codex\config.toml`
Cline	`cline`	`cline_mcp_settings.json` in VS Code's storage for Cline
LM Studio	`lmstudio`	`%USERPROFILE%\.lmstudio\mcp.json`
Zed	`zed`	`%APPDATA%\Zed\settings.json`

Setup only changes the one wc3 entry. Every other server and setting in the file stays as it was, and the file is copied to NAME.wc3-mcp.bak first. A file with comments in it (common in Zed and VS Code) is never rewritten, because that would delete the comments. The settings to paste are printed instead.

Any other MCP app

It is a standard stdio MCP server. Point your app at wc3-mcp.exe with no arguments. wc3-mcp config cursor prints a ready-made JSON entry with the real path filled in, which most apps accept as is.

Configuration

The Warcraft III folder is found automatically from the Windows registry, then C:\Warcraft III, C:\Program Files (x86)\Warcraft III and C:\Program Files\Warcraft III. When yours is somewhere else, either

install with wc3-mcp install --all --game-dir "D:\Games\Warcraft III", which sets WC3_GAME_DIR in each app's entry, or
pass game_dir to a single tool call.

A game_dir argument wins over WC3_GAME_DIR, which wins over the automatic search. wc3-mcp doctor shows which folder it is using.

Build from source

In PowerShell, with the .NET 8 SDK installed,

powershell

git clone https://github.com/GodMephisto/wc3-mcp
cd wc3-mcp
dotnet test --filter "Category!=Corpus&Category!=GameData&Category!=Doctor"
dotnet publish src/Wc3.Mcp/Wc3.Mcp.csproj -c Release --self-contained -r win-x64 -o dist-mcp
.\dist-mcp\wc3-mcp.exe install --all

The apps then start the exe inside your clone's dist-mcp folder, and that folder is what goes on your PATH, so keep the clone where it is or rerun the last line after moving it.

Exact SDK and package versions are in REQUIREMENTS.md. CascLib.dll must stay beside wc3-mcp.exe.

Tools

105 tools.

Name	Read/Write	Description
asset_list	read-only	List the asset paths an icon or model object field can actually be set to, from the map's own imported files and from the base game.
audit_ability	read-only	Tells you, per ability, PASS or the exact broken link across a placed hero's whole runtime chain, far deeper than audit_hero, which only proves a cast...
audit_fidelity	read-only	Tells you whether a ported object's data came across faithfully, by comparing it and its whole custom-object dependency closure between the SOURCE map it...
audit_hero	read-only	Tells you whether a placed hero's abilities are actually wired up in the map's script, not merely present as object data.
audit_map	read-only	Behavioural audit of a map's object data, read-only.
audit_readiness	read-only	Tells you whether a placed hero's script would actually RUN correctly, not just fire, the gap audit_hero cannot see since it only proves a cast reaches a...
bundle_unit	read-only	Resolve everything a unit depends on, the porting preview.
camera_add	writes	Add a camera at a target position and save the edited map to out_path.
camera_list	read-only	List the map's cameras (war3map.w3c).
camera_remove	writes	Remove a camera and save the edited map to out_path.
camera_set	writes	Set a field on a camera and save the edited map to out_path.
deprotect_map	read-only	Recover the file names a protected map stripped.
diff	read-only	Compare two maps and report which internal files were added, removed or changed.
doctor_check	read-only	Will this map run on Reforged 3.0, and if not, why.
doctor_compare	read-only	What differs between two versions of a map, file by file (added, removed, changed) with names recovered on protected archives, plus object, script and s...
doctor_fix	writes	Repair a COPY of a map for Reforged 3.0 with the doctor's Fix map: protection, fake file tables, scrambled ids, data the 3.0 engine refuses, broken SLK...
doctor_inspect	read-only	Read-only doctor reports on one map.
editor_catalog_get	read-only	Show one World Editor catalog's entries, each with its stored key (the token a map file actually carries), its resolved display name and every payload field.
editor_catalog_list	read-only	List the World Editor's catalog names from UI\WorldEditData.txt with entry counts (TileSets, SkyModels, LoadingScreens, SoundChannels, MapSizes, the brush...
file_get_text	read-only	Read one internal file decoded as UTF-8, with any leading BOM stripped.
file_list	read-only	List the archive's internal entries with their CURRENT size, which reflects a pending replacement rather than the stale original.
file_set	writes	Replace an internal file's bytes verbatim from a disk file and save the edited map to out_path.
force_list	read-only	List the map's forces/teams (war3map.w3i).
force_set_flags	writes	Set a force's alliance/sharing flags and save the edited map to out_path.
hero_install	writes	Install a hero definition into a map and save the result to out_path.
hero_lint	read-only	Validate a hero definition folder before installing it.
hero_roster	read-only	List the playable heroes a map registers, with each hero's rawcode, display name, the string tags from its registration call (typically a role and a...
imports_list	read-only	List the map's import table (war3map.imp) against what the archive actually holds, so a table entry with no file behind it and a file absent from the table...
lint	read-only	Pre-flight the map.
list_files	read-only	List the map archive's internal files, each with its name (null = unnamed/protected entry), size in bytes, whether wc3ctl knows/parses the format, and for...
map_info	read-only	Show a Warcraft III map's metadata.
map_info_get	read-only	Read the map's editable scenario fields (war3map.w3i).
map_info_set	writes	Set a scenario field and save the edited map to out_path.
new_map	writes	Create a blank, World-Editor-openable map (.w3x) at out_path.
object_field_options	read-only	The legal values for one object-data field, taken from what the base game data actually uses for it.
object_form	read-only	Get an object as an editable FORM rather than a flat field dump.
object_get	read-only	Get an object's merged fields (base game data overlaid by the map's deltas), each labeled 'base' or 'map', with field names resolved.
object_list	read-only	List the map's custom/modified objects of one Object Editor kind.
object_new	writes	Create a new custom object derived from a base rawcode (a fresh unused rawcode is allocated) and save the edited map to out_path.
object_set	writes	Set a field on an object of one Object Editor kind and save the edited map to out_path (only that kind's war3map.* file is re-serialized).
palette_doodad	read-only	List the doodad types placeable on a map, the palette to consult before place_doodad.
pathing_paint	writes	Paint pathing bits over a circular or square brush and save the edited map to out_path.
place_doodad	writes	Place a doodad instance at (x, y) on the map's doodad layer (war3map.doo) and save the edited map to out_path.
place_item	writes	Place a preplaced item of the given type at world (x, y) and save the edited map to out_path.
place_region	writes	Define a rectangular region on the map's region layer (war3map.w3r) and save the edited map to out_path.
place_start_location	writes	Place or move a player's start location at world (x, y) and save the edited map to out_path.
place_unit	writes	Place a unit of the given type, owned by a player, at world (x, y) and save the edited map to out_path.
placed_doodad_get	read-only	Show one placed doodad's full state by creation number.
placed_doodad_remove	writes	Remove a doodad already placed on the map and save the edited copy to out_path.
placed_doodad_set	writes	Set one field on a doodad already placed on the map and save the edited copy to out_path.
placed_doodads_list	read-only	List every doodad and destructable already PLACED on the map (war3map.doo), each with the creation number needed to edit or remove it, plus its type...
placed_unit_get	read-only	Show one placed unit's full state by creation number.
placed_unit_remove	writes	Remove a unit already placed on the map and save the edited copy to out_path.
placed_unit_set	writes	Set one field on a unit already placed on the map and save the edited copy to out_path.
placed_units_list	read-only	List every unit already PLACED on the map (war3mapUnits.doo), each with the creation number needed to edit or remove it, plus its type rawcode, owner,...
player_list	read-only	List the map's player slots (war3map.w3i).
player_set_force	writes	Move a player into a force (team) and save the edited map to out_path.
port_unit	writes	Port a unit (its custom-object closure + imported assets + strings, and best-effort its JASS trigger closure) from a source map into a target map,...
region_list	read-only	List the map's rectangular regions (war3map.w3r), each with its creation number, name, and bounds.
region_remove	writes	Remove a region by name and save the edited map to out_path.
render_model	writes	Render an object's model (map-imported .mdx/.mdl) to a PNG written at out_path.
repair_generated	writes	Repair a map that wc3ctl itself generated, whose preplaced-hero helper block is too narrow for the heroes installed into it, and save the repaired map to...
replay_summary	read-only	Read recorded games (.w3g) and report each one's map, length, players, and how and when every player left.
roundtrip	read-only	Verify the map survives a load and save byte for byte.
script_check	read-only	Check the map script for errors that stop it loading, war3map.j or war3map.lua.
script_decompile	writes	Turn every Lua entry of a map that ships as precompiled Lua 5.3 bytecode (war3map.lua or a module it requires, common in YDWE maps) back into Lua source...
script_format	writes	Reprint a Lua map script and save the map to out_path.
script_functions	read-only	List every function declared in the map's compiled script, with where it starts and ends.
script_leaks	read-only	Find handle leaks in a map's war3map.j (locations, groups, forces, effects, timers, text tags, lightning and triggers created and never destroyed), each...
script_references	read-only	Find every use of a name in the map's compiled script.
script_to_lua	writes	Convert a JASS map to a Lua map and save it to out_path.
search	read-only	Search the map's contents for a string, ignoring case.
sound_add	writes	Add a new sound definition (keyed by name) to the map's sound catalog and save the edited map to out_path.
sound_list	read-only	List the map's sound catalog (war3map.w3s).
sound_remove	writes	Remove a sound definition from the map's sound catalog and save the edited map to out_path.
sound_set	writes	Set a field on a sound definition and save the edited map to out_path.
strings_list	read-only	List the map's string table (war3map.wts).
terrain_blight	writes	Set or clear the blight (corrupted ground) flag over a brush, saving the edited map to out_path.
terrain_cliff	writes	Raise/lower/set the cliff (stepped-terrain) level over a brush, saving the edited map to out_path.
terrain_corner_get	read-only	Show one terrain corner's full state.
terrain_corner_set	writes	Set one field on ONE terrain corner and save the edited copy to out_path.
terrain_deform	writes	Raise/lower/set/flatten/smooth ground height over a circular or square brush, saving the edited map to out_path.
terrain_fill	writes	Apply a terrain tool over an inclusive RECTANGLE of corners and save the edited map to out_path, instead of one brush dab at a time.
terrain_info	read-only	The terrain grid's extents in corners, plus the map's ground and cliff tile lists.
terrain_paint	writes	Paint a ground texture over a brush, saving the edited map to out_path.
terrain_ramp	writes	Toggle the ramp (sloped cliff transition) flag over a brush, saving the edited map to out_path.
terrain_stats	read-only	Summarize a map's terrain (war3map.w3e).
terrain_water	writes	Set/raise/lower/remove water over a brush, saving the edited map to out_path.
trigger_add	writes	Add a trigger to a category in the map's GUI trigger tree and save the edited map to out_path.
trigger_add_category	writes	Add a category to the map's GUI trigger tree and save the edited map to out_path.
trigger_add_eca	writes	Add an event, condition or action to a GUI trigger and save the edited map to out_path.
trigger_catalog_describe	read-only	Show full detail for one GUI-trigger function by name (e.g.
trigger_catalog_list	read-only	List GUI-trigger functions from the World-Editor catalog (UI\TriggerData.txt), optionally filtered by kind and/or a name/display-name search.
trigger_recover_from_script	writes	Rebuild a browsable GUI trigger tree (war3map.wtg) for a map that has NONE, by decompiling the compiled script the game runs, and save the result to out_path.
trigger_remove	writes	Remove a trigger item (a category, a trigger or a comment) from the GUI trigger tree and save the edited map to out_path.
trigger_remove_eca	writes	Remove one event, condition or action from a GUI trigger by its zero-based position, and save the edited map to out_path.
trigger_rename	writes	Rename a trigger item (a category, a trigger or a deleted stub) in the GUI trigger tree and save the edited map to out_path.
trigger_set_eca_enabled	writes	Enable or disable ONE event, condition or action within a trigger, the World Editor's per-line toggle rather than the whole-trigger one, and save the edited...
trigger_set_enabled	writes	Enable or disable a GUI trigger and save the edited map to out_path.
trigger_set_initially_on	writes	Set whether a GUI trigger starts switched on, and save the edited map to out_path.
trigger_set_run_on_map_init	writes	Set whether a GUI trigger runs on map initialization, and save the edited map to out_path.
triggers_read	read-only	Read the map's GUI trigger tree (war3map.wtg) plus the custom-text bodies (war3map.wct) and the script language.
uabi_profile	read-only	Measure unit ability lists (uabi) across many maps at once, one row per map.
unit_abilities	read-only	Every ability a unit has, each tagged with where it comes from.
validate	read-only	Check the map for structural problems.

Safety

Writing tools require out_path to differ from the input map. The original is never overwritten.

Limits

Windows x64 only (native CascLib). Tools that query base-game data need a Warcraft III Reforged install.

Troubleshooting

Start with wc3-mcp doctor. It shows where the exe is, whether CascLib.dll is beside it, which Warcraft III folder it uses and which apps are set up.
Game not found. Run wc3-mcp install --all --game-dir "<your Warcraft III folder>", or pass game_dir to the tool.
An app does not list the tools. Restart it fully. Claude Desktop needs a quit from the tray, not just closing the window.
A settings file was not changed. It has comments or is not valid JSON, so the settings to paste were printed instead. wc3-mcp config <app> prints them again.
Protected maps. Pass listfiles to deprotect_map to supply community name lists.

Credits

Built on

Library	Author
War3Net (War3Net.Build, War3Net.IO.Mpq, War3Net.Drawing.Blp, War3Net.CodeAnalysis.Decompilers)	Drake53 and contributors
CascLib	Ladislav Zezula
CascLib.NET	Kizari
ImageSharp	Six Labors and contributors
MCP C# SDK (ModelContextProtocol)	Model Context Protocol project
Microsoft.Extensions.Hosting	Microsoft, .NET Foundation

Used directly: Luashine/jass-history (inventory change study), pjass (JASS syntax checking), devoltz and Arakunido (SLK repair guide), and the Hive Workshop community (command line arguments).

Learned from, among many others, HiveWE (stijnherfst), Warsmash and Retera's Model Studio (Retera), WC3MapTranslator (ChiefOfGxBxL), Wurst, TheHelper and the Hive Workshop. The full list of every project and community studied, 197 in all, is in CREDITS.md.

Warcraft III is made by Blizzard Entertainment. This project is unofficial, is not affiliated with or endorsed by Blizzard, reads your own install and ships no game files.