supercell-mcp

License: MIT Node

One MCP server covering three Supercell game APIs — Clash of Clans, Clash Royale, and Brawl Stars. They share an auth model and response style, so a single server with prefixed tool names beats three near-identical ones.

Read-only. These APIs expose no write or messaging endpoints at all, so there is nothing here that can change game state.

Runs over stdio, registered in ~/.claude.json as supercell.

Tools

Prefixes: coc_ Clash of Clans, cr_ Clash Royale, bs_ Brawl Stars.

Clash of Clans	Clash Royale	Brawl Stars
`coc_get_player`	`cr_get_player`	`bs_get_player`
`coc_get_clan`	`cr_get_clan`	`bs_get_club`
`coc_get_clan_members`	`cr_get_clan_members`	`bs_get_club_members`
`coc_search_clans`	`cr_search_clans`	`bs_get_rankings`
`coc_get_current_war`	`cr_get_player_battlelog`	`bs_get_player_battlelog`

Layout

src/client.js        shared auth + fetch, one base URL per game
src/clashofclans.js  coc_* tools
src/clashroyale.js   cr_* tools
src/brawlstars.js    bs_* tools
src/index.js         McpServer construction + stdio transport

The IP allowlist gotcha

Supercell API keys are bound to the IP address they were created for. When the home IP changes, every call starts returning 403 accessDenied even though the key is perfectly valid and unexpired.

That failure mode looks like an auth bug and isn't one. To fix it, mint a new key for the current IP at the relevant developer portal:

Check the current public IP with curl -s https://api.ipify.org (already an allowed command in ~/.claude/settings.json).

Setup

Requires Node 20+. Mint a key per game at the portal listed above, for your current public IP, then save each one as credentials/<game>.json:

credentials/clashofclans.json
credentials/clashroyale.json
credentials/brawlstars.json

Each holds {"token": "..."} — see the matching *.example.json. credentials/ is git-ignored. A game whose key file is absent simply fails on first call with a message naming the file and its portal; the other games keep working.

npm ci
npm start
claude mcp add supercell -- node <path>/supercell-mcp/src/index.js

Tests

npm test

Registration across all three games, tag encoding, and the missing-key error message. No network and no credentials.

Notes

Player and clan tags start with # (e.g. #2PP0JCVL). The # is URL-encoded before the request — pass tags with the # included.
Tags are unambiguous across games but not portable between them; a Clash Royale tag won't resolve against the Clash of Clans API.