io.github.RdyGamingPublished by GitHub account RdyGamingv0.8.0Updated Nov 3, 2026
MCP server for WoW addons: Lua API, UI source, CVars, art, linting, plus model export to glTF/OBJ.
Local MCP server for World of Warcraft addon development: in-game Lua API, Blizzard UI source, CVars, art lookups, linting, and headless model export.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
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
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.
Requires Node 20+. Nothing to clone, nothing to build.
Add -s user to make it available in every project instead of just the current
one. Verify with claude mcp list.
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:
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.
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:
Codex reads TOML, not JSON. Either run codex mcp add wow -- npx -y hated-wow-mcp
or add this to ~/.codex/config.toml:
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:
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.
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:
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.
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:
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.
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:
That should print all 27 tools.
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.
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.
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:
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.
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.
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 client is using. Both can run at the same time.
Two things worth knowing:
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.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:
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.
All settings are optional, see .env.example.
All of it is synced from public mirrors by the scripts in src/sync/, so it
tracks patches without anyone hand-maintaining a list.
API reference
Blizzard's UI source
Authoring
Game data and art
Model export (reads your local install directly)
The exporter opens the CASC storage under your game folder directly and writes
into the folder you name, keeping the game's own folder layout, so the relative
texture paths in the files resolve in Blender. MTL paths use
forward slashes because Blender's importer mangles backslash-relative ones. It
needs sync game-data for the listfile and one small extra sync (sync all
runs both):
That fetches table layouts from WoWDBDefs and decryption keys from TACTKeys; no
game files are downloaded. The first export in a session takes about 30 seconds
while the storage index loads. Data synced before 0.8.0 lacks the NPC gear
tables, so run sync model-data again after updating. Not covered yet: armor
that ships as extra skinned meshes (some recent sets), hair and face textures on
humanoids, and player characters.
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:
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:
Blizzard_Deprecated* shims, which exist
precisely to redefine removed APIs.Re-run after a patch. wow_api_stats and wow_data_status show what you have
and when it was synced.
Those are the commands for a clone. An installed copy has no package scripts, so
it uses the sync subcommand instead:
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.
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.
Frame:SetPoint is found, but
the server does not know that Button inherits it from Frame. Searching the
bare method name works.camelot) at Interface 16001, so it has its
own index and does not share Classic Era's. Both upstream mirrors carry it,
so it has the same five lists as retail. The Battle.net product is wowf and
the install folder is _forever_; the old _classic_beta_ folder from the
beta is no longer detected.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.wow_texture_export decodes a texture to PNG from your own
installation.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.
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.
Issues and pull requests welcome at github.com/RdyGaming/hated-wow-mcp.
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.
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.
MIT, see LICENSE. The model exporter includes code from wow.export (MIT, Kruithne and Marlamin); see THIRD_PARTY.md.
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.
Source: README.md at commit b0893aa
Search the in-game Lua API
Search World of Warcraft's in-game Lua API — the functions an addon can call from inside the client. Covers namespaced functions (C_Item.GetItemInfo), legacy globals (UnitHealth), and widget methods (Frame:SetPoint). Results include full argument and return signatures. Use this before writing any addon code that calls the game.
limitqueryrequiredflavornamespaceSearch in-game events
Search the events an addon can register with frame:RegisterEvent, and show each event's payload arguments in order. Use this whenever writing an OnEvent handler, so the argument list matches what the client sends.
limitqueryrequiredflavorSearch API enums, structures and constants
Search the Enum.*, Constants.* and structure tables the in-game API uses — for example Enum.ItemQuality or the AuraData structure returned by C_UnitAuras. Searching for a member name finds the table that contains it.
kindlimitqueryrequiredflavorCompare API availability across clients
Check whether a function, event or type exists in each game client (retail, Classic progression, Classic Era, WoW Forever). Use this before writing code that has to run on more than one flavor, or to explain why something works on Classic but not retail.
namerequiredShow what API data is loaded
Report which API index, UI source and game data sets this server has, when each was synced, and how large it is. Use this to confirm the data is present and current before relying on other tools.
Takes no parameters.
Search Blizzard's XML frame templates
Search the virtual XML templates that ship with the game — the frames an addon can inherit by name to get Blizzard's own look and behaviour (buttons, scroll lists, panels, tooltips). Shows the inheritance chain, attached mixins and where each is defined. Use this instead of writing frame art from scratch.
typelimitqueryrequiredflavorSearch Blizzard's Lua mixins
Search the mixin tables Blizzard's UI uses — reusable method sets attached to frames via the XML mixin attribute or CreateFromMixins. Searching a method name finds the mixin that defines it. Use this to reuse Blizzard's behaviour or to understand what a template's methods do.
limitqueryrequiredflavorLook up console variables (CVars)
Find the game's console variables — the settings behind SetCVar/GetCVar. Covers every CVar the client registers, and for the ones Blizzard's own UI touches, shows how it reads them, where, and what the options screen calls them. Use this before writing SetCVar, or to discover which CVar controls a piece of game behaviour.
limitqueryrequiredflavorusedOnlySearch Blizzard's UI source code
Regex-search the full Lua and XML source of the 348 Blizzard addons that ship with the client. This is the ground truth for how the game itself does something — event handling, secure frames, data providers, layout. Use it when the API reference tells you what a function is but not how it is meant to be used.
extpkglimitflavorcontextpatternrequiredignoreCasepathContainsRead a file from Blizzard's UI source
Read a Lua or XML file from Blizzard's shipped interface source, by the path that wow_ui_grep or wow_ui_template_search reported. Use this to see a full implementation in context rather than a single matching line.
pathrequiredflavorendLinestartLineList Blizzard's shipped UI packages
List the Blizzard_* addon packages that ship with the client, optionally filtered. Use this to find which package owns a piece of the UI before grepping it, e.g. Blizzard_ActionBar for action buttons.
filterflavorLint addon Lua against a game client
Analyse addon Lua for problems specific to World of Warcraft: APIs that were removed or moved into a namespace in the target client, unknown events, taint (calling protected functions, overwriting Blizzard globals, touching secure frames in combat), and performance traps. Run this on any addon Lua before shipping it, and whenever porting between clients.
codepathflavordisableknownGlobalsValidate interface XML
Validate WoW interface XML against Blizzard's own UI.xsd: unknown or misspelled elements and attributes, invalid nesting, bad enum values, and structural mistakes like a virtual frame with no name. Run this on every XML file an addon loads — the client silently ignores what it does not understand, so these mistakes are otherwise invisible.
xmlpathValidate an addon .toc manifest
Validate a .toc manifest: interface version against the target client, flavor suffix consistency, unrecognised directives the client silently drops, SavedVariables names, and files listed but missing (or present but unlisted). Run this whenever an addon fails to load or shows as out of date.
tocpathfileNameGenerate an addon skeleton
Generate a complete, working addon skeleton: .toc manifests for the chosen clients, an event-dispatch Core.lua with SavedVariables handling and a slash command, and optionally an XML frame template with its Lua mixin and a Settings-API options panel. Use this to start a new addon rather than writing boilerplate by hand. By default it only returns the files. With `write` it saves them into the addon folder, and it refuses if any of the files already exist unless `overwrite` is also set.
namerequirednoteswriteauthorflavorsversionoverwritewithFramewithOptionsslashCommandsavedVariablesShow the local WoW installation
Report the World of Warcraft installations found on this machine — their paths, flavors, build numbers, and the addons currently installed. Use this to confirm which client tools will target and to discover addon folders to lint.
Takes no parameters.
Look up game files and FileDataIDs
Find game art and asset files by name, and get the FileDataID and texture path an addon needs to reference them. Covers every interface texture and icon (and models and maps when the full index is synced). A numeric query is treated as a FileDataID and resolved back to its path. Use this whenever writing SetTexture, SetNormalTexture or SetModel.
extlimitqueryrequiredunderincludeNonInterfaceFind an icon texture
Search the game's icon textures by name and return the path and FileDataID for each. Icons follow a naming convention (spell_fire_*, inv_sword_*, ability_warrior_*), so searching by theme works well. Use this to pick an icon for a button, an addon compartment entry, or a .toc IconTexture.
limitqueryrequiredFind a texture atlas element
Search the named texture atlas elements the UI uses with SetAtlas, the modern way to reference Blizzard art, since an atlas name carries its own size and coordinates. Returns dimensions, the sheet FileDataID and the exact SetAtlas call. Prefer atlases over raw texture paths for UI art. Atlases differ between clients, so name the flavor you are writing for: an atlas that exists on retail may not exist on WoW Forever or Classic.
limitqueryrequiredflavorShow game data availability
Report which game data sets are synced — the file/FileDataID index and the texture atlas index — with counts and sync dates, and what to run for any that are missing. Use this when a game data lookup returns nothing.
Takes no parameters.
Search game models
Find M2 (creature, doodad, prop) and WMO (building, dungeon) models in the game's listfile by path fragment, or resolve a numeric FileDataID. Returns the FileDataID and path to pass to wow_model_export. Needs the game-data sync.
kindlimitqueryrequiredExport a game model
Export a model from the local WoW install's game files into a folder, headless. M2 models become glTF with animations (or GLB/OBJ); WMO models become OBJ+MTL (or glTF). Textures are decoded to PNG beside the model in the game's folder layout, so relative texture paths resolve in Blender. The first call opens the game storage and takes about 30 seconds. Needs the game-data and model-data syncs.
modelrequiredflavorformatoutputDirrequiredanimationssplitGroupsSearch creatures and NPCs
Find creatures and NPCs by name (or creature id, or display id) in the local game files, with the model each one uses. Opens the game storage, so the first call takes about 40 seconds. Use the id with wow_creature_export.
limitqueryrequiredflavorExport a creature or NPC with its skin
Export a creature or NPC as glTF with animations and its skin textures, headless. Beasts and monsters get their display skin and geosets. Humanoid NPCs (built from a player race model) get the right race and sex model, the NPC's hair, beard and similar geosets, the baked NPC skin and their worn armor (boots, robes, tabards and so on). Helms, shoulders and the NPC's weapons are written as separate models beside it, with the bone and position each one attaches to. Written to <outputDir>/creatures/.
flavorformatdisplayIdequipmentoutputDirrequiredanimationscreatureIdExport a game texture as PNG
Decode a BLP texture from the local WoW install to PNG, keeping the game's folder layout under outputDir. Accepts a FileDataID or listfile path.
flavortexturerequiredoutputDirrequiredSearch game maps
Find maps (continents, instances, battlegrounds) by name, directory or id in the local game files. Also converts a world position to the terrain tile that holds it. Opens the game storage, so the first call takes about 40 seconds.
xyqueryrequiredflavorExport map terrain
Export terrain tiles of a map as OBJ with a texture, headless. Give a map id from wow_map_search plus tiles, or a world position. Texture modes: 'tex0' blends the tile's layers into one PNG (default), 'alpha' writes the layer textures and blend masks, 'none' is geometry only. Optionally places the tile's buildings and props. Written to <outputDir>/maps/<directory>/. Baked high-resolution textures are not supported (they need a GPU).
xymapIdrequiredtilesflavorobjectstextureoutputDirrequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
claude mcp add wow -- npx -y hated-wow-mcp{ "mcpServers": { "wow": { "command": "npx", "args": ["-y", "hated-wow-mcp"], "env": { "WOW_DEFAULT_FLAVOR": "mainline" } } }}{ "servers": { "wow": { "command": "npx", "args": ["-y", "hated-wow-mcp"] } }}[mcp_servers.wow]command = "npx"args = ["-y", "hated-wow-mcp"]env = { WOW_DEFAULT_FLAVOR = "mainline" }startup_timeout_sec = 30{ "mcpServers": { "wow": { "command": "cmd", "args": ["/c", "npx", "-y", "hated-wow-mcp"] } }}npx -y hated-wow-mcp sync allnpx -y hated-wow-mcp sync ui-source -- forever # WoW Forever (Camelot)npx -y hated-wow-mcp sync ui-source -- classic # Mists / Cata / Wrath / TBCnpx -y hated-wow-mcp sync ui-source -- vanilla # Classic Eranpx -y hated-wow-mcp sync ui-source -- mainline # retail only, skip the restnpx hated-wow-mcp --listgit clone https://github.com/RdyGaming/hated-wow-mcp.gitcd hated-wow-mcpnpm installnpm run buildnpm run sync-allnpm test{ "mcpServers": { "wow": { "command": "node", "args": ["C:\\absolute\\path\\to\\hated-wow-mcp\\dist\\index.js"] } }}npm run webPORT=4000 npm run webnpx -y hated-wow-mcp sync model-data$ wow_lua_lint --flavor mainlinelocal n = GetContainerNumSlots(0)
1:9 warning api/moved-to-namespace "GetContainerNumSlots" has moved into a namespace in Retail (Midnight)… -> C_Container.GetContainerNumSlotsnpx -y hated-wow-mcp sync allnpx -y hated-wow-mcp sync game-data -- --fullsrc/ 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 locationsserver.js local web UI backend (npm run web)index.html local web UI frontendtest/smoke.mjs 111 end-to-end checks against real datadata/ bundled API indexes, plus synced ones in a clone