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

Related MCP server: World of Warships Ship Data MCP

Available Tools

Reports (4) — start here

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.

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)

Clans (4)

Vehicles & Tanks (5)

Encyclopedia (6)

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

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