Hated WoW MCP

Hated WoW MCP

An MCP server for writing World of Warcraft addons, and for pulling models out of the game. Free and open source.

It gives your MCP client 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. It can also read your local install and export models headless: creatures and NPCs with their skins, props, and buildings, as glTF or OBJ with PNG textures, ready for Blender.

27 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 with no client 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

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:

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:

{

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

VS Code uses a different top-level key from everyone else:

{

"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:

[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:

{

"mcpServers": { "wow": { "command": "cmd", "args": ["/c", "npx", "-y", "hated-wow-mcp"] } } }

That starts a live server in about 4 seconds. From a clone, "command": "node" with the path to dist/index.js starts in half a second and needs no network.

Tool approvals. 23 of the 27 tools only read local data and declare that (readOnlyHint), so a client that prompts per call can safely skip them. The exceptions are wow_model_export, wow_creature_export, wow_texture_export and wow_map_export, which write into the folder you name, and wow_addon_scaffold. The scaffold 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 with no sync and no waiting.

The UI source corpus and the art/FileDataID lookups are too large to ship, so those nine tools, the CVar lookup included, need a one-time sync. It needs git on your PATH:

npx -y hated-wow-mcp sync all

Before you sync: open [https://wago.tools/](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 _forever_ 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:

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 for what upstream does not publish for it yet.

Verify it worked

Ask in your client: *"Using the WoW MCP, what does C_Item.GetItemInfo return?"* You should get a full 18-value signature. Or run the server directly:

npx hated-wow-mcp --list

That should print all 27 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:

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, which is not part of the published package. Requires Node 20+ and git.

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:

{

"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 before opening a PR.

---

Browse it without an MCP client

Every tool also runs in a local web UI: no client, 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; it is not part of the npm package.

npm run web

Then open [http://localhost:3001](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 client 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. Paste a FileDataID into wago.tools to see the actual image, or decode it to PNG with wow_texture_export.

Set PORT if 3001 is taken:

PORT=4000 npm run web

The UI's dependencies (express, cors) are dev dependencies, so a normal npm install picks them up, and the MCP server itself never imports them.

---

Configuration

All settings are optional, see .env.example.

---

What it knows

| CVars | 1,635 console variables with defaults, categories, scope and Blizzard's own desc