supercell-mcp

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.

15 tools. Runs locally over stdio.

Tools

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

Every tool is annotated readOnlyHint: true. The exact schemas the model sees are in mcp-surface.json.

Related MCP server: Clash Royale MCP Server

Layout

src/shared.js        version, timeouts, error shaping, tool-result helpers
src/client.js        shared auth + fetch, tag and country-code validation
src/clashofclans.js  coc_* tools
src/clashroyale.js   cr_* tools
src/brawlstars.js    bs_* tools
src/index.js         McpServer construction + stdio transport
mcp-surface.json     the committed tool surface CI compares against

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. Supercell's 403 body says which it is, and names the IP it saw, so the error this server returns does too:

Clash of Clans API refused the key: it is not allowed from IP 203.0.113.7. Keys are
bound to the IP they were created for — mint one for 203.0.113.7 at https://developer.clashofclans.com

A key that is simply wrong gets a different message that doesn't mention IPs. Mint a new key for the current IP at the relevant developer portal:

• https://developer.clashofclans.com

• https://developer.clashroyale.com

• https://developer.brawlstars.com

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
claude mcp add supercell -- node /absolute/path/to/supercell-mcp/src/index.js

Or in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "supercell": {
      "command": "node",
      "args": ["/absolute/path/to/supercell-mcp/src/index.js"]
    }
  }
}

The credentials file nobody could have created

Until 1.1.0, the Clash of Clans client read credentials/coc.json, while this README and the tracked example file said clashofclans.json. Following the documentation exactly produced a server whose Clash of Clans tools could never succeed — and every test passed, because the mismatch only surfaces at call time, on the user's machine, with real credentials.

The name is fixed (an existing coc.json is still read, so working installs keep working), and each game's client now exposes the file it reads, so a test holds it to the tracked *.example.json beside it. Renaming one without the other fails CI.

Development

npm test               # unit tests — no network, no credentials
npm run lint           # ESLint
npm run surface        # start the server and diff its tool surface against mcp-surface.json
npm run surface:update # re-record mcp-surface.json after an intended change

The tests cover registration across all three games, tag normalisation and encoding, path validation, the credentials-file names, both kinds of 403, and rate-limit and timeout messages. CI runs them on Node 20, 22 and 24, then starts the server with mcp-surface and fails if the tool surface differs from the committed snapshot.

Notes

• Player and clan tags start with # (e.g. #2PP0JCVL). The # is optional and URL-encoded before the request; left raw, it would be read as a fragment and silently truncate the path. Tags are upper-cased, and since the tag alphabet has no letter O, an O is corrected to a zero rather than sent off to 404.

• Every request has a 30-second timeout, error bodies are trimmed before they reach the model, and a 429 says when to retry. Results are compact JSON.

• Tags are unambiguous across games but not portable between them; a Clash Royale tag won't resolve against the Clash of Clans API.

License

MIT — see LICENSE. Changes are recorded in CHANGELOG.md.