hated-wow-mcp

# Hated WoW MCP

[![npm](https://img.shields.io/npm/v/hated-wow-mcp)](https://www.npmjs.com/package/hated-wow-mcp)
[![license](https://img.shields.io/npm/l/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