# Clash Royale MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that wraps the official [Clash Royale API](https://developer.clashroyale.com). Exposes player, clan, card, tournament, and ranking data as MCP tools usable from Claude Desktop or Claude Code.

## Prerequisites

- Python 3.11+
- [`uv`](https://github.com/astral-sh/uv) (recommended) or `pip`
- A Clash Royale developer API token

## Getting an API Token

1. Go to [https://developer.clashroyale.com](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

```bash
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

```bash
# 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):

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

Or if running without `uv`:

```json
{
  "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 |