How do I use Clash Royale MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Clash Royale MCP Server What are the upcoming chests for player #PY9L8G9?" 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.

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

Go to https://developer.clashroyale.com and sign in.
Click My Account → Create New Key.
Enter a name and your current public IP address — tokens are IP-locked.
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