hated-wow-mcp

# Hated WoW MCP [](https://www.npmjs.com/package/hated-wow-mcp) [](LICENSE) **An MCP server for writing World of Warcraft addons.** Free and open source. It gives your AI assistant three things it otherwise guesses at: the **in-game Lua API** for the client you are targeting, **Blizzard's own shipped UI source** so it can see how the game itself does something, and the **game's art and file data** so texture references are real rather than invented. 20 tools. Setup for Claude Code, Claude Desktop, Cursor, Cline, Antigravity, Codex and VS Code is below, and anything else that speaks MCP works too. Or [browse them in a local web UI](#browse-it-without-an-ai-client) with no AI at all. > ### ☕ Support this project > Hated WoW MCP is free and always will be. If it saves you time, you can buy me > a coffee — it genuinely helps keep it maintained through patch cycles. > > ### **[buymeacoffee.com/rdygaming](https://buymeacoffee.com/rdygaming)** Everything here is about code that runs *inside* the client. There is no Battle.net web API in this server — no armory lookups, no auction house. --- ## Quick start Requires **Node 20+**. Nothing to clone, nothing to build. ### Claude Code ```bash claude mcp add wow -- npx -y hated-wow-mcp ``` Add `-s user` to make it available in every project instead of just the current one. Verify with `claude mcp list`. ### Claude Desktop Edit your config file: | OS | Path | | --- | --- | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | > **Windows Store install?** If that path doesn't exist, look under > `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\` instead. Add the `mcpServers` block. **If the file already has other keys, keep them** — merge this in rather than replacing the file: ```json { "mcpServers": { "wow": { "command": "npx", "args": ["-y", "hated-wow-mcp"], "env": { "WOW_DEFAULT_FLAVOR": "mainline" } } } } ``` Then **fully quit Claude Desktop from the system tray** and reopen it — closing the window is not enough, and the config is only read at startup. ### Other clients It is a standard stdio MCP server, so any MCP client can run it. What differs is the config format. The shapes below come from each client's own documentation. | Client | Where | Format | | --- | --- | --- | | Cursor | `.cursor/mcp.json` in a project, or `~/.cursor/mcp.json` | same `mcpServers` JSON as above | | Cline | MCP Servers panel, then Configure (CLI: `~/.cline/mcp.json`) | same `mcpServers` JSON | | Antigravity | `~/.gemini/config/mcp_config.json`, or Settings, Customizations, Open MCP Config | same `mcpServers` JSON. Its docs ask for absolute command paths | | Windsurf | its MCP config file | same `mcpServers` JSON | | VS Code | `.vscode/mcp.json`, or the `MCP: Open User Configuration` command | **`servers`**, not `mcpServers` | | Codex | `~/.codex/config.toml` | **TOML**, see below | **VS Code** uses a different top-level key from everyone else: ```json { "servers": { "wow": { "command": "npx", "args": ["-y", "hated-wow-mcp"] } } } ``` **Codex** reads TOML, not JSON. Either run `codex mcp add wow -- npx -y hated-wow-mcp` or add this to `~/.codex/config.toml`: ```toml [mcp_servers.wow] command = "npx" args = ["-y", "hated-wow-mcp"] env = { WOW_DEFAULT_FLAVOR = "mainline" } startup_timeout_sec = 30 ``` Raise `startup_timeout_sec` from Codex's default of 10. The first `npx` run has to download the package, which took about 9 seconds on a fast connection and would time out on a slower one. Claude Code has the same knob as `MCP_TIMEOUT`. **On Windows**, some clients start servers without a shell, and plain `npx` then fails to launch at all (`ENOENT`). Wrap it in `cmd`: ```json { "mcpServers": { "wow": { "command": "cmd", "args": ["/c", "npx", "-y", "hated-wow-mcp"] } } } ``` That starts a live server in about 4 seconds. From a [clone](#running-from-a-clone), `"command": "node"` with the path to `dist/index.js` starts in half a second and needs no network. **Tool approvals.** 19 of the 20 tools only read local data and declare that (`readOnlyHint`), so a client that prompts per call can safely skip them. The exception is `wow_addon_scaffold`. It writes files only when you pass `write`, and it refuses to overwrite an addon that already exists unless you also pass `overwrite`. If you use auto-approve, leave that one out of the list. See `mcp-config.example.json` in this repo for a starting file. ### Then sync the game data The Lua API indexes ship inside the package, so **API search, type and event lookup, linting, TOC/XML validation and scaffolding work the moment you add it** — no sync, no waiting. The UI source corpus and the art/FileDataID lookups are too large to ship, so those nine tools — including the CVar lookup — need a one-time sync. It needs **git** on your PATH: ```bash npx -y hated-wow-mcp sync all ``` > **Before you sync:** open **<https://wago.tools/>** once in your browser and > let the page fully load. wago.tools sits behind bot protection, and visiting > it first from the same connection lets the atlas download through. Skip this > and the atlas step may fail with HTTP 403. That fetches a ~44 MB shallow clone of Blizzard's UI source and a ~149 MB listfile — a few minutes on first run. Re-running later is cheap: an unchanged listfile is revalidated rather than re-downloaded, so a no-op sync takes about two seconds. ### Classic and WoW Forever A bare `sync all` (or `sync ui-source`) indexes your default client's UI source, retail unless you set `WOW_DEFAULT_FLAVOR`, **plus every WoW client it finds installed**. With `_classic_beta_` installed, WoW Forever is indexed with no flag. With only retail installed, nothing extra is downloaded. The log says what it chose. To pick clients yourself, name them. That overrides the detection, and every sync adds to the same index rather than replacing it: ```bash npx -y hated-wow-mcp sync ui-source -- forever # WoW Forever (Camelot) npx -y hated-wow-mcp sync ui-source -- classic # Mists / Cata / Wrath / TBC npx -y hated-wow-mcp sync ui-source -- vanilla # Classic Era npx -y hated-wow-mcp sync ui-source -- mainline # retail only, skip the rest ``` Each client is its own ~46 MB checkout, so a machine with all four installed downloads about four times what a retail-only one does. The art data follows the same rule. `sync game-data` builds the texture atlas for your default client plus every installed one, and you can name clients the same way (`sync game-data -- forever`). An atlas is small, a few MB, so this costs far less than the UI source. The file index is shared by every client and is built once. Ask a tool about a client you have not synced and it says so and gives you the command. It does not fall back to retail's source, which would answer with code that may not exist on that client. The API index for all four clients ships in the package, so `flavor: "forever"` works on API search, linting and `.toc` validation with no sync at all. See [Known limits](#known-limits) for what upstream does not publish for it yet. ### Verify it worked Ask your assistant: *"Using the WoW MCP, what does C_Item.GetItemInfo return?"* You should get a full 18-value signature. Or run the server directly: ```bash npx hated-wow-mcp --list ``` That should print all 20 tools. ### Where the data lives Synced data never goes inside the package — that is what makes `npx` work. It lands in your OS cache directory: | Platform | Location | | --- | --- | | Windows | `%LOCALAPPDATA%\hated-wow-mcp\Cache` | | macOS | `~/Library/Caches/hated-wow-mcp` | | Linux | `$XDG_CACHE_HOME/hated-wow-mcp`, else `~/.cache/hated-wow-mcp` | Set `WOW_MCP_DATA_DIR` to override — useful for putting ~70 MB on another drive, or sharing one sync between several installs. `wow_data_status` always reports where it resolved to and why. --- ## Running from a clone You only need this to modify the server, or to use the [local web UI](#browse-it-without-an-ai-client), which is not part of the published package. Requires **Node 20+** and **git**. ```bash git clone https://github.com/RdyGaming/hated-wow-mcp.git cd hated-wow-mcp npm install npm run build npm run sync-all npm test ``` `npm test` should report **111 passed, 0 failed**. On Windows, `setup.cmd` does all five steps and prints the absolute path you need below. A clone keeps its synced data in `data/` beside the source rather than in the OS cache, so working on the server never disturbs an npx install you already have. Point your client at the built entry point instead of npx: ```json { "mcpServers": { "wow": { "command": "node", "args": ["C:\\absolute\\path\\to\\hated-wow-mcp\\dist\\index.js"] } } } ``` On Windows, backslashes must be doubled in JSON. On macOS/Linux use a normal path like `/Users/you/hated-wow-mcp/dist/index.js`. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. --- ## Browse it without an AI client Every tool also runs in a local web UI — no assistant, no API key, no tokens. Useful for looking something up quickly, or for checking what a tool returns before you wire it into a prompt. This one needs [a clone](#running-from-a-clone); it is not part of the npm package. ```bash npm run web ``` Then open **<http://localhost:3001>**. Pick a tool from the sidebar and it builds the form for you: the fields, their types, and the help text all come from the tool's own schema, so the UI always matches what the tool actually accepts. Results render in a Monaco editor with a copy button. This talks to the tools directly — it does **not** speak the MCP protocol, so nothing here interferes with the server your assistant is using. Both can run at the same time. Two things worth knowing: - **Run `npm run sync-all` first.** The UI is only as complete as your synced data; without it the UI source and game data tools return nothing. - **Art tools show paths, not pictures.** `wow_icon_search` and friends return FileDataIDs and texture paths — there is no BLP decoding (see [Known limits](#known-limits)). Paste a FileDataID into [wago.tools](https://wago.tools) to see the actual image. Set `PORT` if 3001 is taken: ```bash PORT=4000 npm run web ``` The UI's dependencies (`express`, `cors`) are dev dependencies — a normal `npm install` picks them up, and the MCP server itself never imports them. --- ## Configuration All settings are optional — see `.env.example`. | Variable | Purpose | | --- | --- | | `WOW_DEFAULT_FLAVOR` | Client to answer for when a tool call doesn't name one: `mainline`, `mists`, `cata`, `wrath`, `tbc`, `vanilla`, `forever`. Defaults to `mainline`. | | `WOW_INSTALL_PATH` | Your WoW folder. Auto-detected if unset. | | `WOW_ADDON_PATH` | AddOns folder the file tools read and write. Confines them to that directory. | --- ## What it knows | Data set | Contents | Source | | --- | --- | --- | | Lua API index | 6,335 functions, 1,783 events, 1,676 enums/structures, 6,704 globals (retail; Classic and Classic Era indexed separately) | Blizzard's own generated `/api` documentation, mirrored at [Gethe/wow-ui-source](https://github.com/Gethe/wow-ui-source) | | UI source | 4,036 files across 348 `Blizzard_*` packages — 4,044 inheritable XML templates, 3,488 mixins, 26,859 mixin methods | Same mirror | | CVars | 1,635 console variables with defaults, categories, scope and Blizzard's own descriptions; 451 also carry usage evidence from the UI source | [Ketho/BlizzardInterfaceResources](https://github.com/Ketho/BlizzardInterfaceResources) + UI source | | UI schema | Blizzard's `UI.xsd`, parsed for element/attribute validation | Same mirror | | File index | 172,175 interface files including 36,624 icons, mapped to FileDataIDs | [wowdev/wow-listfile](https://github.com/wowdev/wow-listfile) | | Atlas index | Named `SetAtlas` elements with sizes and coordinates, one index per client at an exact build (17,467 retail, 20,454 WoW Forever) | [wago.tools](https://wago.tools) DB2 exports | All of it is synced from public mirrors by the scripts in `src/sync/`, so it tracks patches without anyone hand-maintaining a list. --- ## Tools **API reference** | Tool | Purpose | | --- | --- | | `wow_api_search` | Find a function with its full argument and return signature | | `wow_api_event_search` | Find an event and its payload arguments, in order | | `wow_api_type_search` | Find an `Enum.*`, `Constants.*` or structure table | | `wow_api_diff` | Compare availability across retail / Classic / Classic Era | | `wow_api_stats` | Show which indexes are loaded and when they were synced | **Blizzard's UI source** | Tool | Purpose | | --- | --- | | `wow_ui_template_search` | Find an inheritable XML template, with its inheritance chain | | `wow_ui_mixin_search` | Find a mixin by name or by one of its methods | | `wow_cvar_search` | Find a CVar: default, category, scope, whether it is protected, and how Blizzard uses it | | `wow_ui_grep` | Regex-search all 4,036 shipped Lua/XML files | | `wow_ui_read_file` | Read a shipped source file in context | | `wow_ui_list_packages` | List the `Blizzard_*` packages | **Authoring** | Tool | Purpose | | --- | --- | | `wow_lua_lint` | Removed/moved APIs, unknown events, taint, performance traps | | `wow_xml_validate` | Validate interface XML against Blizzard's `UI.xsd` | | `wow_toc_validate` | Validate a `.toc`: interface version, flavor suffix, file list | | `wow_addon_scaffold` | Generate a working addon skeleton | | `wow_install_info` | Report local installs and installed addons | **Game data and art** | Tool | Purpose | | --- | --- | | `wow_file_search` | Path ↔ FileDataID, both directions | | `wow_icon_search` | Find an icon and get both usable reference forms | | `wow_atlas_search` | Find a `SetAtlas` element with size and coordinates | | `wow_data_status` | Show which game data sets are synced | --- ## Why the linter is worth running It is built on the per-flavor index rather than a hand-written deprecation list, so it knows things that are true *for the client you are targeting*: ``` $ wow_lua_lint --flavor mainline local n = GetContainerNumSlots(0) 1:9 warning api/moved-to-namespace "GetContainerNumSlots" has moved into a namespace in Retail (Midnight)… -> C_Container.GetContainerNumSlots ``` The same code is clean on Classic, because there the global still exists. That distinction is derived from Blizzard's data, not asserted by hand. It also catches the taint mistakes that produce "Interface action failed because of an AddOn" — calling protected functions, reassigning Blizzard globals, touching secure frames during combat lockdown. **Measured false-positive rate**, checked by running both validators across Blizzard's own shipped code: - XML validator: **0 of 1,091** files report an error. - Lua linter: **48 of 2,551** files (1.9%), and those are almost entirely correct — they are Blizzard's own `Blizzard_Deprecated*` shims, which exist precisely to redefine removed APIs. --- ## Keeping it current Re-run after a patch. `wow_api_stats` and `wow_data_status` show what you have and when it was synced. | Command | Fetches | Notes | | --- | --- | --- | | `npm run sync-api` | Lua API index for all three clients | ~1,700 small HTTPS requests | | `npm run sync-ui-source` | Blizzard UI source (shallow git clone, ~44 MB) | Re-run fast-forwards | | `npm run sync-game-data` | Listfile + atlas tables | Add `--full` for models/maps/sounds | | `npm run sync-all` | All three | | Those are the commands for a clone. An installed copy has no package scripts, so it uses the `sync` subcommand instead: ```bash npx -y hated-wow-mcp sync all npx -y hated-wow-mcp sync game-data -- --full ``` `sync-api` is checkout-only — it regenerates data that ships inside the package, so an installed copy gets a newer API index by upgrading rather than syncing. The data comes from public upstream mirrors, so re-syncing picks up patch changes without waiting on a release here. Note that those mirrors typically lag a live patch by hours to days. **Re-syncing is cheap when nothing changed.** The 149 MB listfile is revalidated with its `ETag`, so an unchanged one costs a single round trip rather than a fresh download, and the index is left alone rather than rebuilt — a no-op `sync-game-data` finishes in about two seconds. Pass `--force` to ignore the cache and rebuild regardless. **The server tells you when it has gone stale.** Once a synced index is more than 30 days old, answers drawn from it carry a one-line warning, and `wow_data_status` reports the age of each set. Stale data is the failure mode worth catching: a confident answer about a function or texture that a patch has since removed is worse than no answer at all. ### wago.tools access **Open <https://wago.tools/> in a browser and let it load before running `sync-game-data` or `sync-all`.** The site is behind bot protection, and a browser visit from the same connection clears the way for the atlas download that follows. Doing this first avoids most atlas failures. If the atlas step still reports HTTP 403, wago.tools is refusing the connection outright — it blocks many datacentre, cloud and VPN IP ranges. Run it from a normal desktop connection, with any VPN off. This never blocks the rest of the sync. The file index in the same script comes from GitHub and works regardless, and only `wow_atlas_search` depends on the atlas step — the other 19 tools are unaffected. --- ## Layout ``` src/ config.ts flavors, interface versions, install detection wowapi/ API index loading, search, rendering uisource/ Blizzard UI source index, template/mixin/grep search gamedata/ listfile and atlas lookup lua/ tokenizer, analyzer, rule tables xml/ UI.xsd parser, XML validator toc/ .toc parser and validator scaffold/ addon generator tools/ MCP tool definitions sync/ the three sync scripts, plus their shared entry point paths.ts bundled vs. synced data locations server.js local web UI backend (npm run web) index.html local web UI frontend test/smoke.mjs 111 end-to-end checks against real data data/ bundled API indexes, plus synced ones in a clone ``` --- ## Known limits - **Widget method inheritance is not modelled.** `Frame:SetPoint` is found, but the server does not know that `Button` inherits it from `Frame`. Searching the bare method name works. - **Classic progression flavors share one index.** Blizzard publishes generated docs for the clients that are actually running; Cata/Wrath/TBC map onto the Classic index, so answers for those are approximate. - **WoW Forever is missing three lists.** Its client is built on the retail codebase (Blizzard calls the game type `camelot`), so it has its own index, and the API docs and UI source come from Blizzard's own files like every other client. But the community resource repo that supplies the flat global-function list, the event list and the CVar registry has no branch for it yet. So on `forever`: unknown-function lint checks are turned off (with a note saying so, rather than flagging working code), a bare name in `wow_api_diff` reads "not documented" instead of "not available", and `wow_cvar_search` shows only the CVars Blizzard's UI touches, with no defaults, descriptions or protection flags. Once upstream has a branch for it, picking these up is a one-line change to the branch table in `src/sync/api.ts`. - **Atlases are built per client, so each has to be synced.** Retail and WoW Forever share 16,788 atlas names, but 3,666 exist only on Forever and 720 only on retail, so `wow_atlas_search` answers from the client you name and says which build it used. A client whose atlas is not built says so and gives the command; it does not borrow retail's. - **No BLP decoding.** Art tools return paths, FileDataIDs and atlas coordinates — not rendered images. Extracting actual textures needs a CASC tool such as wow.export against your own installation. - **The linter's scope model is approximate.** It is a lexer with a scope stack, not a full Lua parser. It errs toward silence on ambiguous code. --- ## Troubleshooting **Server doesn't appear in Claude Desktop.** Fully quit from the system tray, not just the window. Check the JSON is valid and backslashes are doubled. **"Cannot find module ... dist/index.js".** Only applies when running from a clone: you skipped `npm run build`, or the path in your config is wrong. It must be absolute. On npx, use `"command": "npx", "args": ["-y", "hated-wow-mcp"]` and there is no path to get wrong. **UI source, art or icon lookups return nothing.** Those need the one-time sync. Run `npx -y hated-wow-mcp sync all` (or `npm run sync-all` from a clone), then check `wow_data_status` — it reports where it looked and when that data was built. **The sync fails.** You need `git` on your PATH for the UI source step. For an HTTP 403 on the atlas step, see the wago.tools note in [Quick start](#then-sync-the-game-data). **Data seems stale after an update.** `npx` caches the package. Force the newest release with `npx -y hated-wow-mcp@latest`, or clear it with `npm cache clean --force`. `wow_api_stats` shows which index is actually loaded. **"Filename too long" / "Clone succeeded, but checkout failed" (Windows).** Some Blizzard filenames are 108 characters on their own, so a deep clone path can exceed Windows' 260-character limit. The sync scripts pass `core.longpaths=true` to git to handle this. If you still hit it, clone somewhere shorter — keep the path under about 150 characters (`C:\dev\hated-wow-mcp` is plenty of room) — or enable long paths system-wide in Windows. --- ## Contributing Issues and pull requests welcome at [github.com/RdyGaming/hated-wow-mcp](https://github.com/RdyGaming/hated-wow-mcp). [CONTRIBUTING.md](CONTRIBUTING.md) covers the dev setup, how the two data sets differ, and what to know before adding a tool. Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). The most valuable report is a lookup that returns something **wrong** rather than nothing — there is an issue template for it that asks how you verified the real behaviour, so the fix can be checked against the game. Found a security problem? Please report it privately — see [SECURITY.md](SECURITY.md). ## License MIT — see [LICENSE](LICENSE). Not affiliated with or endorsed by Blizzard Entertainment. World of Warcraft is a trademark of Blizzard Entertainment, Inc. All game data is fetched at runtime from public community mirrors and is not redistributed by this project.