Skip to main content
Glama
wow-forever

wow-forever

by mcditchman
README.md
# 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`.

## 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:
  ```json
  { "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).

## 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](#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](https://zugzugdb.com)** (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](LICENSE). World of Warcraft is a trademark of Blizzard Entertainment; this project is not affiliated with or endorsed by Blizzard or ZugZugDB.