wow-mcp

MCP server that wraps the complete World of Warcraft retail API (Game Data + Profile) as 197 MCP tools. Authenticates via OAuth 2.0 client credentials and is fully region-agnostic — every tool accepts region and locale as optional parameters, so a single server instance can query any region.

Quick start

cp .env.example .env
# Fill in BNET_CLIENT_ID and BNET_CLIENT_SECRET

npm install
npm run build
npm start          # stdio transport

Development

npm run dev        # runs via tsx (no build step)
npm run inspect    # opens MCP Inspector UI
npm run lint       # type-check only
npm test           # run auth integration tests

API coverage

All 196 retail WoW endpoints are registered as individual MCP tools, plus one custom computed tool:

• Game Data API — 161 tools covering achievements, auctions, azerite essences, connected realms, covenants, creatures, guild crests, heirlooms, items, journals, media, modified crafting, mounts, mythic keystones, mythic raid leaderboards, pets, playable classes, playable races, playable specializations, power types, professions, PvP seasons, PvP tiers, quests, realms, regions, reputations, search endpoints, spells, talents, tech talents, titles, toys, and WoW tokens.
• Profile API — 35 tools for character profiles, achievements, appearance, collections, dungeons, encounters, equipment, hunter pets, media, mythic keystone profile, professions, PvP, quests, reputations, soulbinds, specializations, statistics, titles, and guild endpoints.
• Custom — wow_character_achievementsTimeline builds a chronologically sorted timeline of completed achievements (computed, not a raw Blizzard endpoint).

Region & locale

Every tool accepts two optional parameters:

• region — "us" (default), "eu", "kr", or "tw"
• locale — "en_US" (default), or any locale supported by the target region (e.g. "es_MX", "de_DE", "fr_FR", "ko_KR")

No region configuration is needed in the environment. The same Battle.net credentials work across all regions.

Environment variables

See .env.example. Only two are required:

• BNET_CLIENT_ID — Battle.net OAuth client ID
• BNET_CLIENT_SECRET — Battle.net OAuth client secret

Optional auth (OAuth2 client-credentials for the MCP HTTP endpoint):

• MCP_CLIENT_ID — when set (with MCP_CLIENT_SECRET), the /mcp endpoint requires a Bearer token
• MCP_CLIENT_SECRET — shared secret for token exchange
• MCP_TOKEN_TTL_SECONDS — access token lifetime (default: 3600)

To obtain a token, POST /token with grant_type=client_credentials and your client_id + client_secret (form body or HTTP Basic). If neither MCP_CLIENT_ID nor MCP_CLIENT_SECRET is set, the server runs without auth.

Optional tuning:

• LOG_LEVEL — pino log level (default: info)
• HTTP_TIMEOUT_MS — request timeout (default: 15000)
• HTTP_RETRY_LIMIT — retry count (default: 2)
• CACHE_TTL_SECONDS — response cache TTL (default: 300)
• CACHE_SIZE — max cached entries (default: 500)

Testing

npm test

Integration tests use Node's built-in test runner (node:test) via tsx — no extra test dependencies. The suite spins up the server on a random port with test credentials and verifies OAuth2 auth end-to-end:

• Rejects /mcp without a token (401)
• Rejects /token with wrong credentials (401)
• Issues a token with correct credentials (200)
• Allows /mcp with a valid bearer token (200)
• Rejects /mcp with a bogus token (401)

Docker

docker compose build
docker compose up -d

Secrets are injected via .env on the host (not committed). The container runs as a non-root user with production dependencies only.

Architecture

src/
  index.ts                          # entry point — loads env, starts server
  app.ts                            # HTTP server factory (/mcp, /token, /health)
  auth.ts                           # OAuth2 client-credentials token endpoint + bearer validation
  config/
    env.ts                          # zod env parsing (credentials + tuning)
    regions.ts                      # region enum, API hosts, OAuth URL
  mcp/
    tools.ts                        # auto-registers all endpoints + custom tools
    schemas.ts                      # shared zod input schemas
  blizzard/
    tokenManager.ts                 # OAuth client-credentials + single-flight
    client.ts                       # got wrapper: bearer injection, cache, 401 retry
    endpoints/
      types.ts                      # EndpointDef interface, buildPath(), schema helpers
      gamedata.ts                   # 161 Game Data API endpoint definitions
      profileEndpoints.ts           # 35 Profile API endpoint definitions
    schemas/
      characterSchemas.ts           # zod response schemas
      achievementSchemas.ts
    dto/
      characterDto.ts               # normalized character DTO
      timeline.ts                   # achievement timeline builder
  util/
    http.ts                         # got defaults
    cache.ts                        # TTL cache
    logger.ts                       # pino (stderr)
test/
  auth.test.ts                      # OAuth2 auth integration tests

Endpoints are defined declaratively in gamedata.ts and profileEndpoints.ts. Each entry specifies a tool name, path template, namespace type, and zod input schema. The tools.ts module iterates over the registry and auto-registers every entry as an MCP tool, injecting region and locale parameters automatically.