Skip to main content
Glama
colbymk97

Clash Royale MCP Server

by colbymk97
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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

Related MCP server: sysauto Ask MCP Server

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • cfbd-mcp-server

    lenwood
    A
    license
    B
    quality
    D
    maintenance
    An MCP server providing access to college football statistics sourced from the College Football Data API within Claude Desktop.
    9
    27
    MIT

  • Discord MCP Server

    userdeter1
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables Claude Desktop to interact with Discord through a dedicated bot. It allows users to list channels, read message history, and send messages directly from the AI interface.
    2
    -

  • beast-baseball

    mw-jeong
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server for natural language analysis of baseball league data, enabling team statistics, standings, lineup suggestions, and scouting reports via Claude Desktop.
    -