The blizzard-wow-mcp server provides read-only access to World of Warcraft character and game data via the Blizzard API. Key capabilities:
Character Profile: Get summary (level, class, spec, race, faction, guild, item levels, achievement points, last login, Armory URL).
Equipment: List equipped items with slot, name, item level, quality, enchantments, sockets, and stats.
Mythic+: Fetch seasonal rating, best dungeon runs (keystone level, affixes, duration, completion time).
Item Lookup: Search items by name with quality/ilevel filters; retrieve detailed info (stats, weapon damage, effects, durability, vendor prices).
Realm Resolution: Resolve realm names to slugs needed by other tools.
Raw Sub-Resources: Access any other character data (raids, talents, professions, PvP, reputations, collections, achievements, etc.) via a flexible tool that strips redundant objects.
Region & Locale: Configure via environment variables for US, EU, APAC regions and multiple locales.
Run Modes: Operate as a stdio MCP server or a stateless HTTP server for easy integration.
Authentication & Limits: OAuth2 client-credentials flow with token caching, automatic retries, and rate limit handling.
Non-destructive: All tools are read-only, idempotent, and safe to call repeatedly. Character/realm name handling is case-insensitive, with automatic slugification.
Provides tools for retrieving World of Warcraft character data from the Blizzard API, including character summaries, equipment, Mythic+ ratings, realm lookups, and other character sub-resources.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@blizzard-wow-mcp What's the Mythic+ score for my shaman on Draenor?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server exposing World of Warcraft character data from the Blizzard API.
It targets the MCP 2026-07-28 specification via the Python SDK v2 (mcp>=2). Everything it does is read-only: it authenticates with the OAuth2 client-credentials flow, so it can reach any public character profile, but none of the /profile/user/* endpoints — those require the authorization-code flow with an end user in the loop.
Python 3.14+
Blizzard API credentials — create a client at develop.battle.net/access/clients
Related MCP server: wow-api-mcp
uv syncThen set your credentials:
export BLIZZARD_CLIENT_ID=...
export BLIZZARD_CLIENT_SECRET=...Variable | Required | Default | Notes |
| yes | — | Server refuses to start without it |
| yes | — | Server refuses to start without it |
| no |
| One of |
| no |
| Any locale the region supports, e.g. |
uv run server.py # stdio (default)
uv run server.py --http # stateless streamable HTTP on :8000/mcpThe package also installs a blizzard-wow-mcp console script that does the same thing.
{
"mcpServers": {
"wow": {
"command": "uv",
"args": ["run", "--directory", "/path/to/wow-armory-mcp2", "server.py"],
"env": {
"BLIZZARD_CLIENT_ID": "...",
"BLIZZARD_CLIENT_SECRET": "...",
"BLIZZARD_REGION": "eu"
}
}
}
}In --http mode the server is stateless and returns plain JSON, so curl is enough to smoke-test it — no session ID and no initialized notification needed.
Start it in one shell:
BLIZZARD_CLIENT_ID=... BLIZZARD_CLIENT_SECRET=... uv run server.py --httpCheck it is up and negotiating:
curl -s -X POST http://localhost:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'List the tools — the quickest single check that the server is wired up:
curl -s -X POST http://localhost:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'Call a tool, which exercises the credentials and the round-trip to Blizzard. wow_find_realm is the cheapest one — it needs no character name:
curl -s -X POST http://localhost:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"wow_find_realm","arguments":{"query":"twisting"}}}'A few gotchas:
The Accept header must list both application/json and text/event-stream. That is a streamable-HTTP requirement, not optional.
If your shell has HTTPS_PROXY or ALL_PROXY set, add --noproxy '*' or curl will try to proxy localhost and hang.
A tool call that comes back with "isError": true and a 403 usually means bad or unset credentials, or that outbound access to oauth.battle.net is blocked.
Tool | Purpose |
| Level, class, spec, race, faction, guild, item level, achievement points, last login, Armory URL |
| Every equipped item with slot, name, item ID, item level, quality, enchantments, stats, sockets and tier set |
| Mythic+ season rating and best runs, sorted by rating. Defaults to the character's most recent season |
| Find items by name, filtered by quality and item level, to get the ID |
| An item's own record by ID: stats, weapon damage, effects, binding, durability and vendor prices |
| Escape hatch for any other character sub-resource — raid progression, talents, professions, PvP, reputations, collections, and so on |
| Resolve a realm name to the slug the other tools need |
All tools are annotated read-only, idempotent and non-destructive.
Everything except wow_character_resource and wow_find_realm returns structured Pydantic models rather than raw Blizzard JSON. wow_character_resource returns the raw payload with Blizzard's self-referential key/href link objects stripped, which typically removes 30–50% of the tokens without losing anything a model would use. Its resource argument is constrained to a fixed list: achievements, appearance, collections/mounts, collections/pets, collections/toys, encounters/dungeons, encounters/raids, hunter-pets, professions, pvp-summary, quests/completed, reputations, specializations, statistics, titles.
There are two sources of item stats, and they answer different questions.
wow_item reads /data/wow/item/{id}, whose preview_item block carries the item's base form — Blizzard renders it at the item's default bonus list. The endpoint takes no bonus-list or context parameter, so for gear that scales (most modern raid and Mythic+ drops, which ship at many item levels under one item ID) the stats it reports will not match any particular character's copy.
wow_character_equipment reports what a character is actually wearing, rendered with that instance's real bonus list — so its stats, sockets and item_level are authoritative for that character. Each equipped item also carries an item_id, which is what you feed to wow_item.
Neither can resolve arbitrary bonus IDs — an auction listing's bonus_lists cannot be turned into stats through any public endpoint.
wow_item_search is the only way into the item data by name; Blizzard exposes no endpoint that enumerates items. Matching is token-based rather than substring, so Thunderfury matches and fury does not. Results are sorted by item level descending and carry classification only — feed an id to wow_item for the stat block.
The search API filters on a locale-qualified field name (name.en_GB, not name), which makes BLIZZARD_LOCALE load-bearing in a way it is not for any other endpoint. A locale the region does not serve yields either an empty result set or a 400; both are reported with a message naming the locale. If you change BLIZZARD_REGION, change BLIZZARD_LOCALE to match.
The filter encoding — locale-qualified fields, [min,max] ranges, _page / _pageSize — is taken from Blizzard's documentation rather than from a captured response, and lives entirely in _item_search_params. If a live call disagrees, that one function is the only thing to change.
Realm names are slugified automatically — Kil'jaeden becomes kiljaeden, Área 52 becomes area-52 — and character names are lowercased and percent-encoded, so you can pass them as a player would write them.
If a lookup 404s, the likely causes are: the character does not exist on that realm, the realm slug is wrong, the character is below level 10, or it has not logged in since the last expansion. Call wow_find_realm to confirm the slug before retrying, and check BLIZZARD_REGION.
Blizzard's quota is 100 requests/second and 36,000/hour per client. The server caches the access token for its lifetime (refreshing 60s before expiry) and retries once on a 401, so ordinary use stays well inside that.
Linting is configured for ruff (line length 100, targeting py314):
uvx ruff check .
uvx ruff format .uv sync # installs the dev group
uv run pytestThe suite is offline — every Blizzard call is served by an httpx.MockTransport, so no
credentials and no network access are needed:
tests/test_helpers.py — realm slugging, character normalisation, slim(), timestamp
conversion, and the localised-name fallback search results need.
tests/test_client.py — token caching and refresh, the single 401 retry, extra query
parameters merging without clobbering the namespace, and the mapping from HTTP status
codes to readable BlizzardError messages.
tests/test_tools.py — all seven tools, including field mapping, missing optional fields,
equipment stat/socket/set parsing, item detail from preview_item, item search filter
encoding and locale handling, Mythic+ season defaulting and run ordering, and realm-search
matching.
.github/workflows/ci.yml runs ruff and the test suite on Python 3.14 for every pull request,
plus weekly on Mondays at 06:00 UTC and on demand via workflow dispatch.
Pull request runs use uv sync --locked, so they install exactly what uv.lock pins and fail if
the lock has drifted from pyproject.toml. The weekly run uses --upgrade instead, resolving
dependencies fresh so it surfaces upstream releases that break the server — which a run pinned to
the lockfile would never catch.
Get every equipped item with slot, name, item level, quality and enchants.
Args: realm: Realm name or slug. character: Character name, case-insensitive.
Returns: EquipmentSummary with one entry per filled slot.
| Name | Required | Description | Default |
|---|---|---|---|
| realm | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
| items | Yes | |
| realm | Yes | |
| character | Yes | |
| equipped_item_level | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral detail by specifying that it returns one entry per filled slot and that the character name is case-insensitive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a front-loaded main sentence, followed by an Args section and Returns section. It is well-structured with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with an output schema, the description covers the purpose, parameters, and return summary. Annotations cover safety, and the output schema handles return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only lists realm and character without descriptions, but the description supplements with 'Realm name or slug' and 'Character name, case-insensitive.' This adds meaning beyond the bare schema, covering both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Get every equipped item with slot, name, item level, quality and enchants.' This clearly specifies the action, resource, and scope, distinguishing it from sibling tools like wow_character_summary or wow_character_resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned. The tool's usage is implied by its name and description, but it does not indicate when to choose it over sibling tools such as wow_character_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a character's Mythic+ score and best dungeon runs for a season.
Args: realm: Realm name or slug. character: Character name, case-insensitive. season_id: Mythic+ season. Defaults to the character's most recent season.
Returns: MythicKeystoneSummary. Returns an error if the character has not completed a Mythic Keystone dungeon in that season.
| Name | Required | Description | Default |
|---|---|---|---|
| realm | Yes | ||
| character | Yes | ||
| season_id | No |
| Name | Required | Description |
|---|---|---|
| realm | Yes | |
| best_runs | Yes | |
| character | Yes | |
| season_id | Yes | |
| overall_rating | No | Season M+ score |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds beyond that: it notes the 'Returns an error if the character has not completed a Mythic Keystone dungeon in that season' and explains the default season selection, which are useful behavioral details not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose sentence, followed by a structured Args list and a Returns line. It is concise yet covers all necessary details without redundancy, earning each sentence's place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description doesn't need to detail the return structure. It covers parameter semantics, default behavior, and an error condition. The only slight gap is the lack of explicit guidance on when to select this over sibling tools, but the purpose is sufficiently clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. The Args section explains each parameter: realm accepts name/slug, character is case-insensitive, and season_id defaults to the most recent season. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('a character's Mythic+ score and best dungeon runs for a season'), clearly distinguishing it from sibling tools like wow_character_summary or wow_character_equipment. The title 'WoW Mythic+ Profile' reinforces the focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool—when Mythic+ score and best runs are needed—and provides context about seasons and defaults. It doesn't explicitly name alternatives, but the sibling tool names and the tool's specific focus make the use-case evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch any other character sub-resource that has no dedicated tool.
Use this for raid progression ('encounters/raids'), talents ('specializations'), 'professions', 'pvp-summary', 'reputations', 'statistics', 'titles', 'appearance', collections and so on.
Args: realm: Realm name or slug. character: Character name, case-insensitive. resource: One of the allowed sub-resource paths.
Returns:
The Blizzard payload with key/href link objects stripped out.
'achievements' and 'statistics' are very large — prefer a narrower
resource where one exists.
| Name | Required | Description | Default |
|---|---|---|---|
| realm | Yes | ||
| resource | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the response has 'key'/'href' link objects stripped out and warns that 'achievements' and 'statistics' are very large, recommending narrower resources. These are behavioral traits beyond what the annotations (readOnlyHint, idempotentHint) already provide. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args and Returns sections, uses compact bullet-like lines, and every sentence provides essential information. There is no fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers what the tool does, when to use it, parameter semantics, return behavior, and performance caveats. The output schema exists and handles return value structure, so the description need not explain that further. For a generic fallback tool, it is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema schema description coverage is 0%, so the description compensates by explaining each parameter: realm (name or slug), character (case-insensitive), and resource (allowed sub-resource paths with examples). It also adds context on resource selection, such as preferring narrower resources, which is not evident from the enum alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch any other character sub-resource that has no dedicated tool,' which is a specific verb (Fetch) and resource (character sub-resource). It also distinguishes itself from dedicated sibling tools like wow_character_summary and wow_character_equipment by specifying it is for resources without a dedicated tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this tool for sub-resources that have no dedicated tool, and advises 'prefer a narrower resource where one exists.' This provides both when-to-use and when-not-to-use guidance, and implies alternatives (dedicated tools).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the headline profile for a character: level, class, spec, race, faction, guild, item level, achievement points and last login.
Args: realm: Realm name or slug, e.g. 'Twisting Nether' or 'twisting-nether'. character: Character name, case-insensitive.
Returns: CharacterSummary. Call wow_character_equipment or wow_character_mythic_keystone for gear and Mythic+ detail.
| Name | Required | Description | Default |
|---|---|---|---|
| realm | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| race | No | |
| guild | No | |
| level | Yes | |
| realm | Yes | |
| gender | No | |
| faction | No | |
| armory_url | No | |
| active_spec | No | e.g. Elemental |
| active_title | No | |
| last_login_utc | No | ISO 8601 timestamp |
| character_class | No | e.g. Shaman |
| achievement_points | No | |
| average_item_level | No | |
| equipped_item_level | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the tool's safety profile. The description does not disclose any additional behavioral traits such as rate limits, authentication requirements, or edge-case behaviors, but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary of what the tool does, followed by clear Args and Returns sections. Every sentence provides value, with no fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple read tool with two parameters: it lists the returned profile fields, explains parameter formats, and points to related tools for more details. The existence of an output schema and annotations further reduces the need for the description to explain return structures or safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description takes on the responsibility of explaining parameters. It adds concrete meaning by giving examples for realm ('Twisting Nether' or 'twisting-nether') and specifying that character is case-insensitive, going beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the headline profile for a character' and enumerates the specific fields returned (level, class, spec, race, etc.). It distinguishes itself from sibling tools by naming alternatives for gear and Mythic+ detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance by instructing to 'Call wow_character_equipment or wow_character_mythic_keystone for gear and Mythic+ detail,' which clearly differentiates when to use this tool versus its siblings. It also gives parameter usage examples for realm and notes character names are case-insensitive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a realm name to the slug the other tools need.
Use this when a character lookup 404s, to rule out a wrong realm slug.
Args: query: Full or partial realm name, e.g. 'twisting' or 'Área 52'.
Returns: Up to 10 matching realms as {name, slug} pairs, for the configured region.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds the return shape ('Up to 10 matching realms as {name, slug} pairs') and region scoping, which are useful behavioral details beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the purpose, then organized into usage, args, and returns. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup tool with a clear output format, the description covers purpose, usage trigger, parameter semantics, and return limit. The output schema exists, but the description adds the limit and region context, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, but the description fully defines 'query' as 'Full or partial realm name' and provides examples. This completely compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Resolve a realm name to the slug the other tools need,' clearly stating the verb, resource, and purpose. It differentiates from sibling character-lookup tools by focusing on realm resolution rather than character data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit trigger: 'Use this when a character lookup 404s, to rule out a wrong realm slug.' It does not explicitly state when not to use it or name alternatives, so it stops short of full guidance, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct aspect of WoW character data: summary, equipment, Mythic+ details, generic sub-resources, and realm resolution. The generic resource tool is explicitly for sub-resources without dedicated tools, so no overlap exists.
All tool names use lowercase snake_case and the 'wow_' prefix, with four of five sharing 'wow_character_*'. The exception is 'wow_find_realm', which uses a verb and different resource prefix, creating a minor but noticeable pattern deviation.
Five tools is a well-scoped count for a character-information server. It covers core workflows without overwhelming users, and the generic resource tool prevents unnecessary tool proliferation.
The dedicated tools handle the most common character lookups, while the generic resource tool provides access to many additional sub-resources (raids, talents, professions, etc.). This effectively covers the domain of WoW character data without significant gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
This MCP server provides seamless access to Malaysia's government open data, including datasets, w…
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Public MCP server for discovering open jobs. Search, filter, and get application links.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/hjoliveira/wow-armory-mcp2'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
