Skip to main content
Glama
wow-forever

wow-forever

by mcditchman

wow-forever-mcp

Local MCP server for the WoW Forever Blizzard API, so Claude can answer questions about your character while you level and raid. It also records auction house prices over time, so Claude can tell you what's cheap, what's a deal, and what your professions will cost to level.

Requires Node 22.13 or newer (the price history uses Node's built-in SQLite).

Setup

  1. Create a client at https://develop.battle.net/access/clients.

  2. cp .env.example .env and fill in the client ID, secret, region and (optionally) your default character's name and surname.

  3. npm install && npm run build

  4. Optional checks: npm run probe (raw API probe) and node scripts/smoke.mjs (calls the MCP tools).

The server reads .env from the project root, whatever working directory it's started from. Restart Claude (or reconnect the server) after editing .env.

Related MCP server: WoW Armory MCP Server

Register with Claude

<path-to-clone> below is the folder you cloned this repo into.

  • Claude Code, this folder only: the included .mcp.json registers it. Claude Code starts project servers from the project root, so the relative path dist/index.js works. Run npm run build first.

  • Claude Code, everywhere: claude mcp add wow-forever --scope user -- node <path-to-clone>/dist/index.js

  • Claude Desktop (chat): add this to claude_desktop_config.json, then fully quit and reopen the app:

    { "mcpServers": { "wow-forever": { "command": "node", "args": ["<path-to-clone>/dist/index.js"] } } }

    The file is at %APPDATA%\Claude\claude_desktop_config.json on Windows and ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. Microsoft Store installs keep it under %LOCALAPPDATA%\Packages\... or a Claude-Data folder instead. The sure way to find it is Settings → Developer → Edit Config in the app.

Tools

Tool

What it returns

get_character_overview

Profile, talent split, stats and gear in one call

get_character_equipment

Per-slot gear with stats, effects, enchants, durability

get_character_talents

Talent trees, ranks and descriptions

get_character_stats

Character sheet (attributes, crit/hit/avoidance, weapon DPS)

get_character_professions

Skill levels, optionally known recipes

get_character_reputations

Factions sorted by standing, filterable

get_character_quests

Quest log; optionally completed quests (filterable)

get_character_achievements

Totals, recent, in-progress

get_character_encounters

Dungeon / raid boss progress

get_character_media

Render / avatar URLs

get_character_collections

Mounts, pets, toys, heirlooms, transmogs

get_guild

Guild info and roster (class/race resolved)

get_item / search_items

Item game data; include_sources adds drop sources and rates

find_zone / get_zone

Zone ids; zone level range, flight masters, trainers, vendors and quest list

find_quest / get_quest

Quest search by name/zone; quest level, objectives, giver coordinates, chain, rewards

get_npc

NPC level, location and coordinates, drops with rates, quests it gives

search_spells / get_recipe

Spell ids; recipe reagents

lookup_fan_db

One ZugZugDB record (objects such as ore and herb nodes, spells, item sets)

get_rulesets

Rulesets (WoW Forever's replacement for realms)

blizzard_api_get

Raw GET for anything else

The auction house tools are listed below.

Auction house

Blizzard's auction endpoints return only the current listings, with no history. So while the server runs, a collector checks every 15 minutes (AH_POLL_MINUTES) for new auction data. It runs in a background thread, so a large download never slows the tools down. When a house has new data it stores a compact per-item summary: lowest price, median, quantity and listing count. Raw listings aren't kept, apart from a price ladder of the latest snapshot. Hourly summaries are kept for 14 days, then rolled up to one row per item per day, which are kept indefinitely. Everything is stored in .cache/auction.db in this folder.

History builds only while the collector runs, either inside the MCP server while Claude is open or always-on (see Always-on collection). Deal detection needs a few days of history before it says anything (3 by default), and "vs. the 30-day median" figures need a month. An item that has vanished from the latest snapshot is shown as "not listed now", with the price and time it was last seen.

The price, deal and profession tools (every auction tool except get_auction_houses) take an optional house (an id, or alliance / horde / blackwater) and optional name and surname, given together. With neither, they use your default character's faction house. Replies always name the house they used, and the profession tools also name the character.

Tool

What it does

Try asking

get_auction_houses

Lists the houses, which are being collected and why, last snapshot time, days of history, DB size, and whether a background job is collecting (and when it switches itself off)

"Is the auction collector running? How much history do you have?"

get_item_prices

Current lowest price, median and quantity for items (ids or names), with 7- and 30-day medians and how today compares

"What's Copper Bar going for, and is that normal?"

get_price_history

Hourly or daily price series for one item, with min, max and trend

"How has Peacebloom moved over the last week?"

find_auction_deals

Current listings priced well below the 7-day median (default 30% below); flip also shows resale value after the 5% cut

"Anything on the auction house worth flipping right now?"

plan_profession_leveling

A full route from your current skill to a target: crafting steps, shopping list, total cost, buy-bars-vs-smelt-ore for miners

"Plan my Blacksmithing from 125 to 150 at the lowest cost."

find_crafting_profit

Your known recipes ranked by profit: product price after the AH cut minus current reagent cost

"Which of my Blacksmithing recipes make money right now?"

Which houses get collected

The API lists auction houses in sets (15 houses at the time of writing: Alliance, Horde and Blackwater per set). The default, AH_HOUSES=auto, collects all three houses of one market set, picked once for your default character's faction and kept, so alts on either faction have history:

  • The first run downloads every house once (about 85 MB, measured) to see which sets are active.

  • auto then picks the set whose house for your character's faction has the most listings, remembers it in the database, and keeps it. It picks again only if your default character's faction changes, or after npm run reset-data.

  • get_auction_houses says which set it picked and why.

AH_HOUSES=all collects every non-empty house in every set, and a comma-separated list of ids collects just those.

Storage

Measured on real data for the three houses auto typically picks (110, 113 and 116, about 17,100, 20,400 and 3,400 items and variants per snapshot, 40,900 rows in total), and on a 96-hour synthetic history built from those rows:

  • About 24 bytes per hourly row, so roughly 1 MB per snapshot.

  • With a changed snapshot every hour, that's about 23 MB per day, and about 0.33 GB for 14 days with the defaults. It holds steady after that, because older hourly rows are rolled up and deleted. AH_HOURLY_DAYS=7 halves it.

  • The latest price ladder adds about 3 MB, and the item-key table about 2.5 MB.

  • Daily rollups add about 40,900 rows (about 1 MB) per day, roughly 0.35 GB per year with AH_DAILY_DAYS=0 (forever). Set AH_DAILY_DAYS to cap it.

  • AH_HOUSES=all stores about 2.5 times as many rows.

Real usage is lower when houses don't change every hour. get_auction_houses shows the current DB size. To free space, lower AH_HOURLY_DAYS (or set AH_DAILY_DAYS) and restart: the next time new auction data arrives (usually within the hour), the older rows are deleted and most of the space goes back to the disk.

Bandwidth

The collector uses conditional requests, so checking a house that hasn't changed is free. When a house has changed, its snapshot is large. With auto, all three houses together are about 33 MB per changed hour, up to about 0.8 GB per day if every hour changes. AH_HOUSES=all downloads every non-empty house, about 2.5 times as much. To cut it down, list specific house ids in AH_HOUSES.

Settings

Set these in .env (see .env.example). Restart Claude after editing, because chat can't change them.

Variable

Default

Effect

Storage impact

AH_COLLECT

on

off stops the in-server collector. The tools still answer from saved history

off stops growth

AH_HOUSES

auto

auto: all three houses of one market set, picked once for your default character's faction and kept. all: every house with listings. Or ids like 110,113,116

all stores and downloads about 2.5× as much; fewer ids shrinks both

AH_HOURLY_DAYS

14

Days of hourly history kept (0 = forever)

About 23 MB for each day kept with auto, so 7 days is about half of 14. Lowering it frees space

AH_DAILY_DAYS

0

Days of daily rollups kept (0 = forever)

About 1 MB per day with auto, growing until you set a cap

AH_POLL_MINUTES

15

Minutes between checks for new data (1 to 1440)

None. Unchanged checks cost nothing; shorter just notices changes sooner

AH_DB_PATH

.cache/auction.db

Where the history database lives. A relative path is relative to this folder

None

Always-on collection

The collector runs inside the MCP server, so it only records while Claude has the server open. For continuous history, npm run schedule registers a job that runs one short collection every AH_POLL_MINUTES (15 by default) and exits. Nothing stays running between runs.

OS

What npm run schedule creates

Windows

A Task Scheduler task named wow-forever-collect, with a description saying what it is and how to remove it

macOS

A launchd agent com.wow-forever-mcp.collect in ~/Library/LaunchAgents, with errors logged to .cache/collect.log

Linux

A crontab line tagged # wow-forever-collect

It switches itself off when you stop using it. Each scheduled run checks when an auction tool was last used in Claude. After 14 days without one (counted from when you scheduled it, if you haven't used one since), the job removes itself. Run npm run schedule again to turn it back on. get_auction_houses reports whether the job is on, when it last ran, and the date it will switch off if unused, so you can ask "is anything collecting in the background?"

  • npm run schedule -- --dry-run prints what it would do without changing anything.

  • npm run unschedule removes exactly that job (also supports -- --dry-run).

  • Neither runs automatically. Run npm run build first, and re-run npm run schedule if you move the folder.

  • Alternative: leave npm run collect -- --watch running in a terminal. npm run collect on its own does a single collection and exits.

Stop or uninstall

  1. Pause: set AH_COLLECT=off in .env and restart Claude. If you scheduled collection, also run npm run unschedule.

  2. Delete history only: npm run reset-data deletes auction.db (and its -wal / -shm files) after printing the path and size. npm run reset-data -- --all also clears the rest of .cache/ (recipe cache, ZugZugDB page cache, quest index). Add --dry-run to preview. A scheduled job loses its usage record with the database, so it switches itself off at its next run; run npm run schedule again if you want it.

  3. Remove completely:

    • Run npm run unschedule (if you scheduled it) before deleting the folder. A job whose folder is gone can't run, so it can't switch itself off either. If you already deleted it, remove the job by hand: on Windows schtasks /Delete /TN wow-forever-collect /F; on macOS launchctl unload ~/Library/LaunchAgents/com.wow-forever-mcp.collect.plist and delete that file; on Linux remove the # wow-forever-collect line with crontab -e.

    • Unregister the server: claude mcp remove wow-forever (add --scope user if you added it that way), or delete the wow-forever entry from claude_desktop_config.json and restart Claude.

    • Delete the project folder, plus the AH_DB_PATH file if you moved it.

    • Optionally delete the Blizzard API client at develop.battle.net.

Nothing else is installed: no global packages, services or registry entries beyond the optional schedule.

Known limitations

  • House-to-set mapping is unconfirmed. Which set of houses belongs to your ruleset isn't documented. auto collects all three houses of one market set, picked once for your default character's faction (the set whose house for that faction had the most listings) and kept, and says so in get_auction_houses. If the prices look wrong, compare one against what you see in game and set AH_HOUSES to specific ids.

  • No sales data. Blizzard only exposes current listings, so the flip mode can't tell how fast something resells. It judges risk from supply and price stability instead.

  • The first leveling run per profession takes a few minutes. Recipe skill-up levels come from ZugZugDB, which is rate-limited to one request every 2 seconds. The tool replies "loading", and later calls use the cache (30 days).

  • Vendor reagent prices are estimates. Reagents that only vendors sell (thread, flux and the like) are priced from an estimate, not from the auction house.

  • History only exists from when you start collecting. Deals and 7- and 30-day comparisons need days or weeks of data first.

Game-data sources

  • Blizzard API (official): quest text and rewards, quest lists per zone, items, spells, recipes, auctions. It has no quest levels, givers, objectives, NPCs, drop tables or zone info.

  • ZugZugDB (community fan site) fills those gaps. Lines marked Classic data or vanilla reference are patch 1.12 data not yet confirmed in Forever.

    • This server only fetches single record pages (/quest/{id}, /npc/{id}, ...) when you ask about something, following the site's robots.txt and terms.

    • It never touches /api/ or /search and never walks through ids.

    • Requests are spaced 2 seconds apart, per the site's crawl delay. If the site answers "too many requests", every request waits for its Retry-After (30 seconds when none is given).

    • Requests identify themselves with a User-Agent that names this repository.

    • Pages are cached in .cache/ for 24 hours (recipe and skill data for 30 days).

  • Quest name search uses an index built from Blizzard's own zone and category quest lists. It's built on first use (~3 s) and cached for 7 days.

  • Wowhead also has a WoW Forever section but blocks automated access, so it isn't used.

Character tools default to the character in .env. Pass name and surname to look up someone else.

WoW Forever API notes (as of Nov 2026, undocumented)

  • Auth: client-credentials token from https://oauth.battle.net/token; host https://{region}.api.blizzard.com.

  • Namespaces: static-forever-{region}, dynamic-forever-{region}, profile-forever-{region}.

  • No realms. Characters are /profile/wow/character/{name}-{surname}, lowercase. Profiles carry ruleset and surname.

  • Characters show up only at level 10+ and after logging out. Data can lag by several minutes.

  • Not working yet: realm endpoints, hunter-pets, and many item IDs (404).

  • Auction responses can be ~9 MB per house (more for the large ones), which is why the auction tools return summaries from the collector rather than raw listings. blizzard_api_get still works for one-off raw requests.

  • Source: https://us.forums.blizzard.com/en/blizzard/t/wow-forever-api-what-works-so-far-plus-a-ts-client/60334

License

MIT. See LICENSE. World of Warcraft is a trademark of Blizzard Entertainment; this project is not affiliated with or endorsed by Blizzard or ZugZugDB.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    • Everything about World of Warcraft: Forever, in the chat app you already use. Anything you'd look up is already in your chat. Close your other tabs. Why thott.bot? - Everything, connected. Quests, items, recipes, NPCs and maps are linked: what a quest needs, where that item drops, where you turn it in, what it crafts. Your AI gets the whole picture in one place, not scraps from dozens of random sites. - Current to the minute. Every new build, patch and hotfix reaches thott.bot within minutes of landing, even the silent ones. - Straight from Blizzard. Game facts come from Blizzard's own files and posts, not old guides or forum guesses. Community guides are labeled as such. What it knows: - Your characters: link Battle.net and your AI knows the characters you actually play, their gear, talents, quests and more, updated every time you log out. - Patch notes and changes: every build and hotfix, and exactly what each changed. - Quests and leveling: every quest, its chain, route and rewards, and leveling guides. - Talents and builds: the builds players run right now, counted daily from millions of real characters at every level, every spec's talent pick rates, and every talent change. - Spells and abilities: every spell and ability, and every change to each. - Classes and races: every class, race and racial, and what Forever changed for each. - Items and gear: every item and item set, where it drops and who sells it. - Crafting and professions: every profession, recipe and reagent, what each reagent makes, and profession leveling guides. - Auction house: live prices on every WoW Forever auction house, hourly. - The world: zones, maps, flight paths, dungeons, raids and bosses, battlegrounds. - Collections: mounts, pets, toys, achievements, reputations and holidays. - Interface and addons: every setting, key binding and chat command, the addon API and banned addons. - Blizzard news: news and developer posts (blue posts) from the official forums. In ChatGPT and Claude, ask to see it: your characters' sheets with the gear and stats they logged out with, the game's own tooltips, clickable talent trees, quest chains, maps and before-and-after cards. For every WoW Forever player, from first-timers to theorycrafters and addon developers.

      https://mcp.thott.bot/mcp
    • World of Warcraft: Forever lore and player-observed drops, vendors, quests, professions and talents.

      https://everloot.app/mcp/public
    • Teamfight Tactics data & AI coaching for Claude and ChatGPT — 19 tools, built-in Riot key.

    • Claude reads and writes a real-life RPG character sheet from the eighty self-improvement app.

      https://mcp.80l.app

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides comprehensive World of Warcraft guild analytics, player character analysis, and auction house market data through the Blizzard Battle.net API. Supports both Retail and Classic WoW with real-time market insights, guild roster management, and demographic analytics.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for World of Warcraft that provides 26 tools for accessing characters, guilds, realms, game data, and auction house info via Blizzard's Battle.net APIs. It enables natural-language queries for character audits, Mythic+ reviews, market analysis, and more.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to read Wowhead data for every World of Warcraft version, including items, drops, quests, NPCs, spells, guides, news, and patch notes, through a read-only server that needs no account, key, or browser.
      26 npm
      MIT