Clash Royale MCP Server

A Model Context Protocol (MCP) server that wraps the official Clash Royale API. Exposes player, clan, card, tournament, and ranking data as MCP tools usable from Claude Desktop or Claude Code.

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• A Clash Royale developer API token

Getting an API Token

1. Go to https://developer.clashroyale.com and sign in.
2. Click My Account → Create New Key.
3. Enter a name and your current public IP address — tokens are IP-locked.
4. Copy the token.

IP locking gotcha: If your IP changes (home network, VPN, etc.) your token will return 403 errors. Either create a new key or use the RoyaleAPI community proxy (see below).

Using the RoyaleAPI Proxy (recommended for local dev)

The proxy at https://proxy.royaleapi.dev/v1 forwards requests to the official API without IP locking. Set it via the env var:

CLASH_ROYALE_BASE_URL=https://proxy.royaleapi.dev/v1

Installation

git clone <repo>
cd clash-royale-mcp

# Copy and fill in your token
cp .env.example .env
# Edit .env: set CLASH_ROYALE_API_TOKEN=your_token_here

# Install with uv
uv sync

# Or with pip
pip install -e .

Running Locally

# Test the server directly (exits immediately — use fastmcp dev for interactive testing)
python -m clash_royale_mcp.server

# Interactive MCP inspector (recommended for development)
fastmcp dev src/clash_royale_mcp/server.py

Claude Desktop Integration

Add to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "clash-royale": {
      "command": "uv",
      "args": ["run", "clash-royale-mcp"],
      "env": {
        "CLASH_ROYALE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Or if running without uv:

{
  "mcpServers": {
    "clash-royale": {
      "command": "python",
      "args": ["-m", "clash_royale_mcp.server"],
      "cwd": "/path/to/clash-royale-mcp",
      "env": {
        "CLASH_ROYALE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Available Tools

Player

Tool	Description
get_player	Full player profile: trophies, level, wins/losses, clan, card collection
get_player_battlelog	Recent battle history (up to 25 battles) with decks and outcomes
get_player_upcoming_chests	Upcoming chest sequence in the player's cycle
get_player_recent_decks	Deduplicated deck analysis with win rates and usage counts

Clan

Tool	Description
get_clan	Full clan profile and member roster
search_clans	Search clans by name, location, or score thresholds
get_clan_members	Paginated clan member list
get_clan_warlog	Clan war history
get_clan_current_war	Current active war state

Cards

Tool	Description
get_cards	Full card catalog (~100+ cards); cached after first call

Tournaments

Tool	Description
search_tournaments	Search open tournaments by name
get_tournament	Tournament details by tag
get_global_tournaments	All currently active global tournaments

Locations & Rankings

Tool	Description
get_locations	List locations/regions with their IDs
get_clan_rankings	Top clan rankings for a location or globally
get_player_rankings	Top player trophy rankings for a location or globally
get_clanwar_rankings	Top clan war rankings for a location or globally

Environment Variables

Variable	Default	Description
CLASH_ROYALE_API_TOKEN	(required)	Your API token from developer.clashroyale.com
CLASH_ROYALE_BASE_URL	https://api.clashroyale.com/v1	API base URL; override for proxy