Wargaming MCP Server for World of Tanks Console

A Model Context Protocol (MCP) server that gives AI assistants (Claude Desktop, VS Code Copilot, or any MCP client) live access to the Wargaming API for World of Tanks Console (Xbox & PlayStation). Ask your assistant natural-language questions like "How good is player X on Xbox?" or "Compare the IS-7 and the Maus" and it answers with real data.

Built with TypeScript, the official MCP SDK, and Zod schema validation. Also includes a standalone Node.js CLI for quick API queries from the terminal.

Features

• 30 MCP tools covering players, clans, vehicles, progress tracking, and the full Tankopedia encyclopedia
• Session & progress tracking — the Wargaming API only exposes lifetime totals, so this server stores local stat snapshots and diffs them: get-player-progress answers "how did I do tonight?" with battles, win rate, average damage, and a per-tank breakdown over the interval. Snapshots also accumulate passively whenever you run get-player-report.
• One-shot player reports — get-player-report takes just a nickname and combines account search, overall stats, derived metrics (damage ratio, survival rate, frags/battle), top tanks, best performers, and clan membership into a single answer
• Side-by-side tank comparison — compare-tanks "IS-7" "Maus" produces a full armor/firepower/mobility table
• Side-by-side player comparison — compare-players puts two players' stats, most-played tanks, and best performers next to each other
• Whole-clan reports — get-clan-report fetches stats for every member in batched requests and aggregates them: battle-weighted win rate, activity buckets, top performers
• Human-readable output everywhere — tank IDs and achievement IDs are resolved to real names via a cached Tankopedia lookup
• Smart tank search — fuzzy name matching (IS-7, IS 7, and IS7 all work)
• Client-side rate limiting & retries — requests are throttled to Wargaming's 10 req/s limit and automatically retried on transient errors
• Response caching — encyclopedia data is TTL-cached (1 h), so name lookups are effectively free after the first call
• Actionable error messages — common API errors (invalid key, IP restrictions, rate limits) come back with a hint on how to fix them
• CI + smoke tests — GitHub Actions builds the project and verifies the MCP protocol layer on every push

Available Tools

Reports (4) — start here

Tool	Description
get-player-report	Complete player profile from a single nickname: stats, derived metrics, top tanks, best performers, clan
compare-tanks	Side-by-side comparison table of two tanks (by name or ID): armor, gun, ammo, mobility, view range
compare-players	Side-by-side comparison of two players: win rate, damage, survival, most-played and best tanks
get-clan-report	Aggregate report for an entire clan (by tag, name, or ID): battle-weighted averages, activity, top performers

Progress Tracking (3)

The Wargaming API only returns lifetime totals — these tools store local snapshots (one small JSON file per player) and diff them to reconstruct recent performance.

Tool	Description
snapshot-player	Record a baseline snapshot of a player's current lifetime + per-tank stats
get-player-progress	Performance since a snapshot: battles, win rate, avg damage, per-tank breakdown over the interval; auto-saves a new snapshot
list-player-snapshots	List the stored snapshots for a player

Snapshots live in ~/.wargaming-mcp-server/snapshots (override with the WARGAMING_MCP_DATA_DIR env var) and are also recorded passively by get-player-report, so history accumulates from normal use.

Player & Account (8)

Tool	Description
search-players	Find players by nickname
get-player-stats	Overall combat statistics (battles, win rate, damage, XP)
get-player-achievements	Account-wide achievements with real medal names
get-player-vehicles	Per-tank stats summary for a player
get-detailed-player-vehicle-stats	Deep per-tank stats incl. survival rate, garage status, company battles
get-player-vehicle-achievements	Vehicle-specific achievements, ribbons, and series
get-player-by-xuid	Resolve a Microsoft XUID to an account
get-player-by-psnid	Resolve a PlayStation Network ID to an account

Clans (4)

Tool	Description
search-clans	Find clans by name or tag
get-clan-info	Clan details (members, description, created date)
get-player-clan-info	A player's clan membership and role
get-clan-glossary	Clan role definitions

Vehicles & Tanks (5)

Tool	Description
get-vehicles	Browse/filter vehicles by nation, type, tier, or name
search-tanks-by-name	Fuzzy tank search by name (exact-match optional)
get-tank-details	Tank specifications (HP, speed, weight, pricing)
get-vehicle-characteristics	Full configuration profile: armor, gun, ammo, engine, turret, radio, suspension — accepts a tank name or ID, with optional custom module IDs
get-tank-modules	Guns, engines, radios, suspensions, turrets by nation/tier

Encyclopedia (6)

Tool	Description
get-tankopedia-info	Game version, nations, vehicle types, achievement sections
get-maps	Battle maps with descriptions
get-encyclopedia-achievements	All achievements, medals, and ribbons
get-encyclopedia-modules	Detailed module database
get-crew-roles	Crew roles and their skills
get-vehicle-upgrades	Equipment and consumables for a specific tank (by name or ID)

Quick Start

Prerequisites

• Node.js 18+
• A free Wargaming API key from the Wargaming Developer Portal

  ⚠️ Choose a Mobile application type unless you have a static IP — Server keys are locked to an IP allowlist and will return INVALID_IP_ADDRESS from other addresses.

Option A: Run via npx (no install)

Once published to npm, no clone or build is needed — point your MCP client at npx:

{
    "mcpServers": {
        "wargaming": {
            "command": "npx",
            "args": ["-y", "wargaming-mcp-server"],
            "env": {
                "WARGAMING_API_KEY": "your_api_key_here"
            }
        }
    }
}

Option B: Install from source

git clone https://github.com/lHyperionl/WG-Console-MCP-server.git
cd WG-Console-MCP-server
npm install

# add your API key
copy .env.example .env   # Windows (use `cp` on macOS/Linux)
# edit .env and set WARGAMING_API_KEY

npm run build

Run the tests

npm test           # full suite: protocol checks + live API calls
SKIP_LIVE=1 npm test   # offline: protocol checks only (no API key traffic)

The smoke test builds the project, spawns the MCP server over stdio, verifies all 30 tools are registered, and exercises live calls against the Wargaming API — including the full search → report, compare-tanks, compare-players, get-clan-report, and snapshot → progress flows.

Architecture

src/
├── index.ts              # Entry point: registers tools, starts stdio transport
├── api.ts                # API client: rate limiting, retries, TTL cache, error hints
├── types.ts              # Shared Wargaming API response types
├── format.ts             # Number/percentage formatting helpers
├── encyclopedia-cache.ts # Cached tank & achievement name resolution
├── player-lookup.ts      # Shared nickname -> account resolution
├── snapshots.ts          # Local stat snapshot store for progress tracking
└── tools/
    ├── players.ts        # 8 player/account tools
    ├── clans.ts          # 4 clan tools
    ├── vehicles.ts       # 5 vehicle tools
    ├── encyclopedia.ts   # 6 tankopedia tools
    ├── reports.ts        # get-player-report, compare-tanks, compare-players, get-clan-report
    └── progress.ts       # snapshot-player, get-player-progress, list-player-snapshots

Cross-cutting concerns live in one place: every tool goes through makeWargamingRequest, which enforces the 10 req/s limit with a sliding-window throttle, retries transient failures (HTTP 5xx/429 and REQUEST_LIMIT_EXCEEDED) with backoff, caches encyclopedia responses for an hour, and annotates well-known API errors with fix-it hints.

Claude Desktop Integration

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
    "mcpServers": {
        "wargaming": {
            "command": "node",
            "args": ["C:\\absolute\\path\\to\\wargaming-mcp-server\\build\\index.js"],
            "env": {
                "WARGAMING_API_KEY": "your_api_key_here"
            }
        }
    }
}

Restart Claude Desktop, then try:

• "Give me a full report on player 'PlayerName' on Xbox"
• "Compare the IS-7 and the T110E5"
• "Compare me and my clanmate 'OtherPlayer'"
• "Take a snapshot of my stats" — then, after a session: "How did I do tonight?"
• "Give me a report on the clan with tag 'STEEL' — who are the top performers?"
• "Show me all tier 10 German heavy tanks"
• "Which of PlayerName's tanks has the best win rate?"

VS Code users: the repo ships a ready-made .vscode/mcp.json for the built-in MCP support.

CLI Tool

For quick queries without an MCP client:

node wot-cli.js search-players "ProGamer"
node wot-cli.js player-stats 1088722148
node wot-cli.js player-vehicles 1088722148
node wot-cli.js search-vehicles 10 germany heavyTank
node wot-cli.js vehicle-characteristics "IS-7"
node wot-cli.js tank-modules guns germany 10
node wot-cli.js search-clans "STEEL"
node wot-cli.js maps

Run node wot-cli.js with no arguments for the full command reference.

Continuous Integration

Every push runs the CI workflow: install → TypeScript build → smoke test. If a WARGAMING_API_KEY repository secret is configured, the live API checks run too; otherwise CI validates the MCP protocol layer offline.

Troubleshooting

Symptom	Cause / Fix
INVALID_IP_ADDRESS	Your key is a Server-type application restricted to specific IPs. Add your current IP in the developer portal, or create a Mobile-type key.
INVALID_APPLICATION_ID	The API key in .env is wrong or was deactivated.
REQUEST_LIMIT_EXCEEDED	Wargaming rate limit (10 req/s) — the server throttles and retries automatically; if it persists, reduce parallel clients.
Server exits immediately	WARGAMING_API_KEY is not set — check your .env or MCP client env config.

Notes

• Xbox and PlayStation share a single unified API endpoint (api-modernarmor.worldoftanks.com); the platform parameter is kept for forward compatibility and labeling.
• This project is not affiliated with Wargaming. It is a community tool using the public Wargaming API.

License

ISC