# How it works

**For:** anyone deciding whether wow-stats is for them. **At the end:** you know what runs
where, what leaves your computer, and which page to read next.

wow-stats never talks to the game. WoW Forever and a few well-known addons already write down
what you do: levels, quests, loot, deaths, gear, auction prices. wow-stats reads those files
after the game saves them, and turns them into pages you can act on.

![How it works: the game and your addons save SavedVariables files, the shipper reads them every 5 minutes and sends new events to the server, which builds your pages and answers your AI](https://sam-dumont.github.io/wow-mcp/images/how-it-works.svg)

## The four pieces

**The addons.** [Polestar](https://github.com/fitzforge/polestar) and its Recorder do most of
the work: route steps, levels, sessions, zones, deaths. Syndicator adds your bags, Auctionator
your auction house scans, Questie or Altoholic the quests you did before. wow-stats ships no
addon of its own. The full list: [Addons it reads](https://sam-dumont.github.io/wow-mcp/game-data/addons/).

**SavedVariables.** That's where addons keep their data: plain text files in the game's `WTF`
folder. WoW writes them only when you `/reload`, log out or switch character. A crash or
Alt+F4 loses what happened since the last save, for every addon. So the one habit worth
having: `/reload` after a dungeon, an auction house scan, or before a break.

**The shipper.** A small program on the computer you play on. Every 5 minutes it reads what
changed in `WTF` (and the combat log, if you turned it on), turns it into events and sends them
to your server with your own upload password. It keeps a copy of everything it sent in a
`WoWArchive` folder in your home folder. It never reads your WoW or Battle.net password, and
nothing outside the WoW folder. [What it sends](https://sam-dumont.github.io/wow-mcp/play/getting-started/#what-the-program-on-your-computer-does).

**The server.** One `docker compose up` on a small box: 2 vCPU and 2 GiB of RAM run it for a
handful of players, and a year of one player's events takes a few MiB. It keeps the events
and works out everything else from them, every time you open a page: pace, upgrades,
dungeons, plans. Someone you know can run it for you, and then you skip this part.

## What you get out of it

**Your page.** Behind your login, with everything: your pace against Polestar's route, the
next upgrade per slot and where it drops, the dungeon worth running, your climb, one journal
entry per play session. A tour: [Your page at a glance](https://sam-dumont.github.io/wow-mcp/play/your-page/).

**Pages for others, if you want them.** A sealed copy for the friends you pick (the key sits
in the link, so the server can't read it) and a public one cut down to an allow list. Neither
ever shows other players, what killed you, or where your character is right now.
[What's shared](https://sam-dumont.github.io/wow-mcp/play/privacy/).

**Your AI.** The server speaks MCP, the protocol Claude, ChatGPT and a dozen other assistants
use to call outside tools. Your assistant asks for your data and does the thinking in your own
account: no model runs on the server, and wow-stats never sees the conversation. When the
assistant quotes a number, the server re-runs the query behind it.
[Connect your AI](https://sam-dumont.github.io/wow-mcp/ai/connect/).

**Battle.net data, optional.** With your own Battle.net API client, the server also fetches
your character's look (for the 3D view) and the WoW Token price; never the auction house, whose
prices come from your own Auctionator scans. Blizzard's terms cap that data at 30 days, so it lives in its own store with a 23-day
retention. [Battle.net data](https://sam-dumont.github.io/wow-mcp/self-host/battlenet/).

## Where to go next

- A friend sent you a link: [Join a friend's server](https://sam-dumont.github.io/wow-mcp/play/getting-started/).
- You want to see it first: [the live demo](https://sam-dumont.github.io/wow-mcp/try/), a made-up priest.
- You want to run it: [Try it at home](https://sam-dumont.github.io/wow-mcp/self-host/try-at-home/), 10 minutes with Docker.
- The parts in detail, for the curious: [Architecture](https://sam-dumont.github.io/wow-mcp/explain/architecture/).
