Clash of Clans MCP Server

A Model Context Protocol (MCP) server that lets Claude (or any MCP client) read your clan's data from the official Clash of Clans API and apply your clan's own rules to it — for war grading, elder promotion screening, and CWL carry-forward decisions.

Built for clan leaders who want AI-assisted clan analysis with reproducible, configurable rules.

Keywords: Clash of Clans, MCP, Model Context Protocol, Claude, Claude Desktop, clan war, CWL, Clan War League, clan management, elder promotion, war analysis, Supercell API.

What you can do with it

Once connected to Claude Desktop (or another MCP client), you can ask things like:

"How did our last war go? Who didn't follow the rules?"

"Should I promote ankit176 to Elder? What's our policy bar?"

"Pull together a CWL carry-forward recommendation for next season."

"Who in the clan has the highest donation ratio this season?"

"Pull our capital raid loot for the last 5 weekends."

The MCP turns each question into the right API calls, applies your configurable rubric (in JSON, edit freely), and returns a leadership-ready answer.

Sample output

After you run it on a finished war, you get something like:

# War Report — vs clash serious (Defeat)

Total attacks used: 26 · Missed: 4 · Avg ⭐/attack: 2.27 · Avg destruction: 83%

## 1. Attack Participation (2/2 expected)
- Used both attacks (12): Justin (#1), Slayer7 (#2), TURBO (#3), ...
- Used only 1 of 2 (2): M@NJ!T (#4), Laeo_Lol XD (#11)
- 🚨 Did not attack (1): Punjabi Pete (#15)

## 2. Rule Compliance
- Clean (3): Justin (#1), aNkiT (#6), joe (#10)
- Violations (12):
  - Slayer7 (#2, TH18): 2nd attack didn't 3⭐ and only hit 80%
  - M@NJ!T (#4, TH18): 1st attack hit base #10 (offset +6); rule = mirror or one down
  - ankit176 (#8, TH17): 2nd attack target offset -3 (should hit lower bases for smart 3⭐)
  - ...

## 3. Performance Leaderboard
| Rank | Name | Pos | TH | ⭐ Earned | Avg Dest % | Score | Grade |
| 1 | Justin | #1 | TH18 | 6 | 100% | 23 | A |
| 2 | Corrupt | #5 | TH17 | 6 | 100% | 20 | A |
...

## 4. Smart-Attack Honor Roll (clean 3⭐ on lower base)
- Justin (#1) → hit base #2 for 3⭐ 100%
- Corrupt (#5) → hit base #9 for 3⭐ 100%

Tools the MCP exposes

API wrappers (read-only):

Workflow tools (the leverage):

Getting started

1. Get a free Clash of Clans API token

This MCP wraps the official Supercell API, which is free but requires a token tied to your IP address.

1. Open developer.clashofclans.com.

2. Click Login and sign in with your Supercell ID (the same one tied to your in-game account — you'll get an email code).

3. Once logged in, go to My Account → Create New Key.

4. Find your current public IP — easiest:

   curl ifconfig.me

5. Fill in the form:

   • Key Name: anything (e.g. coc-mcp)

   • Description: anything (e.g. MCP server for clan analysis)

   • Allowed IP Addresses: paste the IP you got from curl ifconfig.me

6. Click Create Key. Copy the long JWT token that appears (starts with eyJ...).

   🛡️ The token is IP-locked. If your IP changes (new ISP, VPN, coffee shop), regenerate the key with the new IP, OR run the MCP from a host with a fixed IP (a small VPS, a home server, etc.).

2. Find your clan tag

In-game, tap your clan name → look for the tag like #YV9JRULU. Note: clan tags use uppercase letters and digits only (no O, only 0).

3. Clone and install

git clone https://github.com/justinritchie/clash-of-clans-mcp.git
cd clash-of-clans-mcp
pip install -r requirements.txt

4. Configure your token

cp .env.example .env

Edit .env:

COC_API_TOKEN=eyJ0eXAiOiJKV1Q...    # <-- paste your token
COC_DEFAULT_CLAN_TAG=#YV9JRULU       # <-- your clan tag

The .env file is .gitignored, so your token won't accidentally get committed.

5. Smoke test

python coc_test.py

You should see green checkmarks for every endpoint:

✅ GET /clans/<tag>
   Clan: Broken Arrow (level 27) — 44 members, 793W
✅ GET /clans/<tag>/members
✅ GET /clans/<tag>/warlog
✅ GET /clans/<tag>/currentwar/leaguegroup
✅ GET /clans/<tag>/currentwar

If you get ❌ HTTP 403, your IP doesn't match the token's whitelisted IP. Regenerate the token with your current IP (curl ifconfig.me).

If the CWL leaguegroup returns 404, that's fine — CWL only runs the first ~10 days of each month.

6. Run the unit tests

pip install pytest
pytest tests/ -v

Eight tests should pass. They run against fixture JSON, no API calls.

7. Try the war report CLI

python run_war_report.py

This dumps the full markdown report for your most recent war (whatever state it's in).

Wire it into Claude Desktop

Option A — Use the included installer (recommended)

python install_to_claude_desktop.py

This:

• Backs up your existing claude_desktop_config.json (timestamped)

• Appends a coc entry without touching any other MCPs

• Pulls the token from your .env

• Idempotent — re-running just updates the entry

Then restart Claude Desktop.

Option B — Manual edit

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "coc": {
      "command": "python3",
      "args": ["/absolute/path/to/coc-mcp/coc_mcp_server.py"],
      "env": {
        "COC_API_TOKEN": "eyJ0eXAi...",
        "COC_DEFAULT_CLAN_TAG": "#YOURTAG"
      }
    }
  }
}

Restart Claude Desktop. The coc_* tools will appear.

Cowork or other MCP clients

The MCP runs over stdio. Anything that supports stdio MCP servers will work — point it at coc_mcp_server.py with the env vars set.

Customizing the rubric

The default rules live in config/rubric.default.json:

{
  "war_attack_rubric": {
    "first_attack": {
      "acceptable_offsets": [0, 1],   // mirror or one down
      "min_stars_for_pass": 2
    },
    "second_attack": {
      "preferred_offsets_min": 1,     // must attack lower than your rank
      "must_3_star": true             // smart 3-star expected
    },
    "missed_attack_penalty": -10
  },
  "elder_promotion_rubric": {
    "min_donation_ratio": 0.4,
    "min_hero_progress_pct": 80,
    "min_war_score_last_n": 50
  },
  "carry_forward_rubric": {
    "min_attacks_used_pct": 100,
    "min_avg_stars": 2.0,
    "min_avg_destruction": 75
  }
}

Two ways to customize:

1. Permanently — copy to config/rubric.local.json (gitignored), edit, then point to it:

   COC_RUBRIC_PATH=./config/rubric.local.json

2. Per call — when invoking clash_grade_war or clash_war_report, pass rubric_overrides with just the fields you want to change. They're deep-merged onto the loaded rubric.

   Example: relax the smart-3⭐ rule for one analysis:

   { "war_attack_rubric": { "second_attack": { "must_3_star": false } } }

Limitations (be aware before you start)

• Per-attack data is only available for the current war (state inWar or warEnded). The /warlog endpoint returns summary only (result, totals — no per-attack data). To analyze past wars over time, snapshot /currentwar to disk while state is warEnded. (Future enhancement: a clash_snapshot_war tool.)

• The API is read-only. You cannot promote, kick, accept join requests, edit clan settings, send messages, or change war state. Supercell intentionally doesn't expose write endpoints. This is a diagnostic / advisory tool — it tells you who deserves the action; you take it in-game.

• No clan chat access. Supercell doesn't expose chat. Use a Discord bridge bot if you need chat-based workflows.

• API token is IP-whitelisted. Token breaks if your IP changes. Regenerate or use a fixed-IP host.

• Tenure / "days in clan" is not in the official API. That data lives on third-party sites like clashofstats.com. Future enhancement could scrape it; for now, the elder rubric uses war contribution and donation ratio as proxies.

Project layout

coc-mcp/
├── coc_mcp_server.py             # FastMCP entry — tool registrations
├── coc_mcp/
│   ├── client.py                 # Async COC API client
│   ├── grading.py                # Rubric engine
│   ├── reporting.py              # Markdown generators
│   └── config.py                 # Token + rubric loading
├── config/
│   └── rubric.default.json       # Default rubric (edit freely)
├── tests/
│   ├── fixtures/                 # Sample war JSON for tests
│   └── test_grading.py           # Unit tests
├── coc_test.py                   # Live smoke-test script
├── run_war_report.py             # CLI: dump war report for current war
├── install_to_claude_desktop.py  # Safe installer (backs up first)
└── mcp_config_example.json       # Drop-in for claude_desktop_config.json

Contributing

PRs welcome — especially:

• More workflow tools for common leadership tasks (war post-mortem trends, donation watch, hero progression alerts)

• Tenure scraping from clashofstats.com or similar (worth its own MCP)

• Snapshot store for historical war analysis (sqlite or jsonl)

• War prediction (given roster + opponent, what's the expected outcome?)

• More language SDKs (this is Python; a TypeScript port would help)

If you build something off this, drop a link — would love to see what other clans are doing.

License

MIT — see LICENSE.

Acknowledgements

This product uses data from the Clash of Clans API but is not affiliated with, endorsed, sponsored, or specifically approved by Supercell. Supercell is not responsible for it. For more information see Supercell's Fan Content Policy: supercell.com/fan-content-policy.

Built with FastMCP and the MCP spec.