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

Clan

Cards

Tournaments

Locations & Rankings

Environment Variables