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

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

.\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.

Context and RAG

Out of the box the server answers docs_search from the bundled Warcraft III references, the Big UI-Frame Tutorial and the Editor Ability Insight doc, lexical and offline, and serves each whole as an MCP resource.

For the full corpus and semantic search, install the local index. From your AI app, call the rag_install tool, or from a shell

wc3ctl rag install

It fetches two files, once, and verifies each against a pinned digest. The embedding model BAAI/bge-small-en-v1.5, about 130 MB, and the corpus, about 61 MB from this repo's dataset-v1 release. It then builds a local vector index and a graph. No database, no service, no key, and it is set low on CPU by default. After that docs_search is semantic and the graph tools graph_neighbors, graph_hubs and graph_path are live. wc3ctl rag status reports what is installed.

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.

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,

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

251 tools.

| Name | Read/Write | Description | |---|---|---| | asset_audit | read-only | Flag suspicious imported assets. It reports entries larger than max_bytes, BLP textures whose width or height is not a power of two, a binary .mdx with no .m... | | asset_convert_batch | writes | Convert every texture in a folder to one target format, reusing the shared converter, and write the copies under out_dir with their relative paths preserved.... | | asset_duplicates | read-only | Group the map's imported files whose bytes are identical (by sha256) and report the space each duplicate group wastes. Zero-byte entries are excluded. Read-o... | | asset_import_wire | writes | Add disk files to a map as imports and, when a file is a model or an icon and object names an object, point its matching model or icon field at the new impor... | | 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. Ask this BEFORE setting... | | asset_model_lint | read-only | Scan every imported model (.mdx/.mdl) in the map and report the structural problems a static check can find, a geoset with no material, a material naming a t... | | asset_replace | writes | Replace an asset path everywhere it is referenced (object-data field values, script string literals and the war3map.imp import table) and save the edited cop... | | asset_size_report | read-only | Break the map's imported bytes down by parent folder, largest total first, so the folders that dominate the map's weight are obvious. Read-only. | | asset_thumbnails | writes | Render a thumbnail PNG for every model in a folder, or for every imported model inside every map in the folder, and write them under out_dir. Reuses the mode... | | asset_unused | read-only | List the map's imported files that no object-data field value and no script string literal references, each with the size it holds. A lead to review before d... | | 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 reache... | | 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 was... | | 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. For every ability it verifies the w... | | audit_map | read-only | Behavioural audit of a map's object data, read-only. Where 'validate' answers whether a map can LOAD, this answers whether its abilities do what they CLAIM,... | | 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 han... | | audit_trend | read-only | Run the behavioural audit against two maps and report the findings the second added and removed, grouped by check. Where audit_map answers what is wrong now,... | | bench_compat | read-only | Check every map against every target build and return a pass or fail matrix with the finding counts in each cell, plus the aggregate over the whole grid. Pas... | | bench_leaks | read-only | Run the static leak detector over every map in a folder and report the counts per map and per leak kind, with the hot and repeat totals. The folder sweep the... | | bench_open | read-only | Open every map in a folder through the loader and record the per-map open time in milliseconds, entry count and total decompressed bytes, reporting the slowe... | | bench_perf_gate | read-only | Compare two recorded benchmark result JSON files and report whether any metric regressed by more than a threshold, for use as a CI gate. Each file is an obje... | | bench_schema_coverage | read-only | Measure what object data a schemas corpus carries. One row per schema folder names the build, its era and whether the object data is real (the folder holds i... | | bundle_diff | read-only | Compare two dependency bundles (the JSON written by 'bundle unit -o') by their object and asset members, listing what each adds, removes or renames. | | bundle_merge | writes | Merge two dependency bundles into one, written as JSON at out_path. Refuses when the same rawcode is defined differently in the two bundles (a different kind... | | bundle_unit | read-only | Resolve everything a unit depends on - the porting preview: referenced objects (with custom-to-map flags), asset files, trigger strings, dependency edges and... | | camera_add | writes | Add a camera at a target position and save the edited map to out_path. The input map is NEVER modified in place. Rejects a blank or duplicate name. | | camera_list | read-only | List the map's cameras (war3map.w3c): each camera's name, target position, rotation, angle of attack, distance and field of view. | | camera_remove | writes | Remove a camera and save the edited map to out_path. The input map is NEVER modified in place. | | camera_set | writes | Set a field on a camera and save the edited map to out_path. The input map is NEVER modified in place. Editable fields: Name|TargetX|TargetY|ZOffset|Rotation... | | camera_tour | writes | Add N cameras interpolated between two existing cameras as a smooth tour path, and save the edited map to out_path. Every float field is blended linearly and... | | changelog | read-only | Generate release notes from git log between two refs, grouped by Conventional Commit type (feat, fix, perf, docs, chore and the rest), a heading per group wi... | | ci_all | read-only | Run lint, validate and, when target is given, compat in one pass. Returns one summary