Skip to main content
Glama
Sign In
castle-clash-mcp

castle-clash-mcp

by mmadersbacher
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

castle-clash-mcp

An MCP server that answers Castle Clash from real game data and the engine's own formulas, not from a model's guess.

Ask an LLM how much HP Serratica has at 10 stars level 200 and it guesses. This server computes it: 12000*10 + 305*199 = 180,695, the exact in-game number. Every stat and every combat number comes from the game's data plus formulas recovered from the client → the answer is derived, not remembered.

What it knows

  • 203 heroes, exact base stats per evolution grade → hero_stats_calc, hero_dossier

  • The full stacking model (gear, crest, insignia, talent, soul, holy, runes, ...) folded into effective stats

  • The real damage math, recovered from libgame.so → combat_math

  • 200+ game tables, 426 skills, items, gacha drop odds → game_systems, search_all

  • The effect engine: 59 buffer types resolved to their mechanic → combat_effects

  • Exact skill damage from the numeric coefficients → skill_data, skill_damage

  • A stat-based build generator and scorer → generate_build, build_score

  • A 1v1 fight simulator built on the verified formulas → simulate_fight

The math is written up in docs/GAME_MATH.md: stat scaling, the crit / damage / defense formulas, the attack-type matrix, the effect engine. Each formula is tagged verified or open, with the experiment that closes it.

Related MCP server: Pokémon Champions MCP Server

Install

git clone https://github.com/mmadersbacher/castle-clash-mcp
cd castle-clash-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python scripts/selfcheck.py   # asserts the verified anchors

Wire into an MCP client

claude mcp add castle-clash -- /path/to/castle-clash-mcp/.venv/bin/ccmcp-server

Or in a client config:

{ "mcpServers": {
    "castle-clash": { "command": "/path/to/castle-clash-mcp/.venv/bin/ccmcp-server" }
} }

Tools

Heroes and stats: hero_dossier (one-call hub: stats, every grade, skill damage at the hero's own ATK, recommended build and its grade), hero_stats_calc, hero_sheet, get_hero, hero_level_stats, rank_heroes, compare_heroes, list_heroes, tier_list.

Skills: skill_data (numeric per-level coefficients), skill_damage (exact damage at a given ATK), skill_levels, hero_skills, totem_skill.

Combat: combat_math explains one hit, combat_effects browses the effect taxonomy, simulate_fight runs a duel.

Builds: generate_build ranks talents by the numbers for offense / ehp / balanced, build_score grades one build, recommend_build fills a build with capability-aware picks, check_build flags redundancies and gaps.

Cross-reference: related resolves any name to what connects to it (a skill to the heroes that use it, a hero to its skill, an item to its system).

Game data: game_systems, get_system, system_lookup, search_all, gacha_odds, plus per-catalog lookups (get_crest, get_insignia, get_pet, get_soularm, ...).

The math is checked, not asserted

scripts/selfcheck.py locks the anchors and fails on drift: Serratica 180,695/7,881 and Dynamica 157,700/9,279 (both confirmed against a real account to the unit), plus the crit, crit-damage, damage-reduce and skill-scaling constants. Those combat constants were confirmed by executing the native code, so a wrong sign or a bad edit gets caught immediately.

What is not yet pinned (a few status labels, the energy and attack-speed constants) is listed in the doc, each with the reading or trace that closes it.

Data

Hero stats and the game tables are extracted from the client and the community handbook en.casclash.com. data/sources/MANIFEST.md maps every file to what it is and where it came from. The raw cc_data dump and local scratch are not bundled → the core (stats, combat, sim, builds, dossier) runs without them.

Castle Clash is IGG's game. This is an unofficial fan project, not affiliated with or endorsed by IGG, and the game data belongs to IGG. The code is MIT.

Available Tools

47 tools
build_scoreA

Grade a build by numbers without a fight: effective stats plus EHP (tankiness) and an offense score (ATK x attacks/sec x average crit factor), all from the verified combat math. loadout_json is the same shape hero_stats_calc takes. Use it to compare builds on one hero.

Inputs: hero (required), evo, level, stars, +3 more.

check_buildA

Validate a 5-slot build: flags reflection redundancy (two slots), energy gaps, missing reflection/ATK, signature-talent HP penalties, and revive suggestions. Returns findings + ok.

Inputs: hero (required), pet, crest, talent, +2 more.

combat_effectsA

The effect-engine taxonomy recovered from the binary (docs/GAME_MATH.md sec 9). With no argument: counts by handler category across the 59 in-use BufferTypes. With a buffer_type: that type's mechanic + state bit. Status bits map to crowd control (type 39 = hard CC / halt; type 3 = immunity/cleanse).

Inputs: buffer_type.

combat_mathB

Explain one hit using the engine's exact formulas (recovered from libgame.so, see docs/GAME_MATH.md). attack_type/armor_type 1..5 (Melee, Pierce, Magic, Siege, Hero); player heroes attack as 5. skill_coeff=1.0 for a normal hit or skill%/100 for a skill. Ratings are raw Hero.data stats. Also returns crit chance and crit-damage that the ratings convert to.

Inputs: atk (required), is_crit, armor_type, attack_type, +5 more.

compare_heroesB

Side-by-side computed stats for two heroes at the same stars/level.

Inputs: hero_a (required), hero_b (required), level, stars.

db_statusA

Show row counts and when the data was last refreshed.

Inputs: no named parameters.

effect_at_levelB

Effect of a talent or hero skill at a specific level. kind='talent' or 'hero'. Returns that level's effect text (+ might/cooldown if present) and the full range.

Inputs: kind (required), name (required), level (required).

gacha_oddsA

Drop odds for a gacha pool (by Type): each reward with its weight and probability %. Omit/unknown type returns the list of available pool types.

Inputs: pool_type (required).

game_systemsB

Every Castle Clash data system and its entry count (heroes, skills, talents, crests, insignias, gear, holy, traits, relics, soul, pets, magic, buildings, monsters, gacha, items...).

Inputs: no named parameters.

generate_buildA

Rank the talent and crest slots for a hero by the numbers (build_score), for objective 'offense', 'ehp' or 'balanced', and return the best full build (talent + crest scored together) plus the top options per slot. Pure stat ranking → cross-check recommend_build for the capability caveats.

Inputs: hero (required), top, objective, talent_lvl, +1 more.

get_catalog_entryC

Get one catalog entry (effect/stats where casclash provides them).

Inputs: name (required), category (required).

get_crestC

Career crest (Camp: Oracle/Saint/Brawler/Orderbound/Voidwalker): per-level Attack/HP/Tenacity/Crit/Dodge/Hit_DMG.

Inputs: name (required).

get_enchantmentB

Enchantment = Soul-Arms skill (e.g. 'Bold Ambition', 'Forest Ward'): per-level from game data.

Inputs: name (required).

get_equipmentB

Equipment item (Equipment table): per-level Hp/Attack + effect text.

Inputs: name (required).

get_game_tableB

Rows of a game data table by name (see list_game_tables). Rows carry English *_en fields.

Inputs: table (required), limit.

get_heroA

Full hero record: the complete game data (combat, base per evolution, level curves, main skill per level, totem, icon) merged with tier + build tags.

Inputs: name (required).

get_iconA

Icon path for a hero/skill/item/pet (kind from icon_maps). Omit key to list icon kinds.

Inputs: kind (required), key.

get_insigniaC

Insignia/crest-item (Equipment table, 208 items): per-level Hp/Attack + effect text.

Inputs: name (required).

get_petA

Pet lookup (Pet table): id, mark, and its pet-talent. Note: pets give a team-wide %% aura, browsable here but not folded into hero_stats_calc's per-hero flat stats.

Inputs: name (required).

get_runeC

Rune (Runes table, 101): per-level Hp/Attack + effect.

Inputs: name (required).

get_soularmB

Soul-Arms base stats at a given level (flat Attack/HP/Tenacity added to a hero).

Inputs: level (required).

get_systemC

Rows of a game system (see game_systems). English-annotated (name_en).

Inputs: system (required), limit.

get_talentC

Talent effect and capability tags.

Inputs: name (required).

hero_completeA

The COMPLETE hero record: combat stats, base per evolution, full level curves (Ord/Evo1/Evo2 1-80), main skill per level, totem skill, icon. The authoritative all-in-one hero entry.

Inputs: hero (required).

hero_dossierA

Everything about one hero in a single call: base combat ratings, every evolution grade's exact formula params + 10*/L200 HP/ATK, main + totem skill, tier/role, and a recommended build. Ordinary stats are formula-verified; evolved grades come from live_hero_params (with a reconciliation flag when a multi-form hero mis-extracts its Ordinary grade).

Inputs: hero (required).

hero_level_statsA

EXACT per-level HP/Attack/MOV/Might from casclash's tables (Lv1-80, per evolution), authoritative, no formula. evo = 'Ordinary'|'Evolution1'|'Evolution2'|'max'. For level>80 or higher stars use hero_stats_calc (formula).

Inputs: hero (required), evo, level.

hero_sheetC

EVERYTHING about a hero in one call: complete stats + main skill + totem skill summary + tier + a recommended build. The one-stop hero overview.

Inputs: hero (required).

hero_skillsC

A hero's skills: totem skill (name + level count, from Hero.data naming scheme) and a pointer to the main active skill (via get_hero / hero_level_stats from the wiki).

Inputs: hero (required).

hero_statsA

LIVE fully-computed stats for a hero at a given level (1-200), via casclash's calculator (there is no official IGG API). Returns HP, Attack, ATK SPD, MOV SPD, Attack Range, ACC, Dodge, CRIT, CRIT DMG, CRIT Resist. talent = talent NAME (e.g. 'Tenacity') or id, with talent_lvl 1-10; reincarnation=1 is the normal evolved form. camp(crest)/pet/inscription are numeric ids (0 = none).

Inputs: hero (required), pet, camp, level, +6 more.

hero_stats_calcA

TRUSTWORTHY formula-based stats (validated exactly vs the user's real game: Serratica 10 stars/L200 = 180,695 HP). stat = perStarStars + inc(Level-1); evo=1/2 uses Fandom's exact Legendary evolution params. Optional talent name + level applies its HP/ATK %. Prefer this over hero_stats (casclash caps stars at 4). inscription/soularms/artifact are LEVELS; gear_json is a JSON list of {type:'insignia'|'rune', name, level} — all fold into the returned effective stats (flat HP/ATK on top of the talent-% base).

Inputs: hero (required), evo, soul, level, +12 more.

list_catalogB

List all entries in a catalog category (e.g. pet, crest, trait, signature, buildings, decorations, dungen, watchers, slime, talent, enchantment).

Inputs: category (required), limit.

list_categoriesA

List catalog categories and how many entries each has (talent, enchantment, pet, crest, trait, signature, buildings, decorations, dungen, watchers, ...).

Inputs: no named parameters.

list_game_tablesA

List all 182 game data tables extracted from the APK (buildings, dungeons, pets, soul arms, inscriptions, summon rates, battle pass, guild, monsters, ...).

Inputs: no named parameters.

list_heroesB

List heroes ranked by tier. mode e.g. overall/Guild War/Arena/Dungeons; tier filters (S+, S, A+...).

Inputs: mode, tier, limit.

rank_heroesB

Rank heroes by a computed stat (HP/Attack) at given stars/level. Newest epics may be missing.

Inputs: stat, level, limit, stars.

recommend_buildB

Recommend a full 5-slot build (talent, crest, insignia, enchantment, pet). Pass any slot to fix it (e.g. talent='Wicked Armor'); the engine fills the rest without anti-synergies (reflection in the enchant slot, energy in talent-or-crest) and explains every pick.

Inputs: hero (required), pet, mode, crest, +3 more.

refresh_dataA

Rebuild the database: load seed catalog and (unless seed_only) scrape casclash. limit caps heroes scraped.

Inputs: limit, seed_only.

relatedA

Cross-reference any name: resolve whether it is a hero, a skill, or a catalog item, and return what connects to it (a skill points to the heroes that use it, a hero points to its skill, an item points to its system).

Inputs: query (required).

search_allB

Search across ALL 28 game systems at once (heroes, skills, talents, gear, items, ...).

Inputs: query (required), limit.

search_game_dataA

Full-text search across ALL 182 game tables. Returns matching rows with their table name.

Inputs: query (required), limit.

simulate_fightA

Simulate a 1v1 auto-attack duel between two hero builds using the verified damage formulas (see docs/GAME_MATH.md). Returns the expected winner, each side's DPS, crit chance (with the opponent's Tenacity), and time-to-kill. reduce_a/reduce_b are optional damage-reduce ratings from each build. Skills, energy, heals, shields and crowd control are not yet modeled.

Inputs: hero_a (required), hero_b (required), evo, level, +7 more.

skill_damageA

Exact skill damage for a given ATK, using the verified skill primitive (ceil(damage% * ATK / 100), from docs/GAME_MATH.md). Defaults to the skill's max level. Returns per-hit damage and the target count.

Inputs: atk (required), skill (required), skill_level.

skill_dataA

Numeric per-level data for a skill (from Skill.data): damage % of ATK, targets, duration, effect %. 274 of 426 skills carry a real damage coefficient. Use skill_damage to turn a % into an actual number.

Inputs: skill (required).

skill_levelsB

Per-level effect + English description for any of the 421 game skills (from decoded Skill.data). skill = name (e.g. 'Divine Shield') or numeric name_id.

Inputs: skill (required).

system_lookupB

One entry from a system by English name, with its full per-level/per-star data (e.g. system_lookup('holy','Divine Roots'), ('crest','Revive Crest I'), ('gear','Dragon Ring')).

Inputs: name (required), system (required).

tier_listC

Ranked tier list for a mode (overall/Guild War/Arena/Dungeons/HBM-LBF/Blitz).

Inputs: mode, limit.

totem_skillB

A hero's Totem skill with English description per level (from totem_skills_full).

Inputs: hero (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    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

    TDQS

    C2.9/5.0

    Scored across 47 tools

    Disambiguation2/5

    There are several overlapping clusters: get_hero/hero_complete/hero_sheet/hero_dossier all claim to return the full hero record, and the get_insignia/get_crest/get_rune/get_enchantment/get_equipment group is hard to differentiate at a glance. Descriptions carry nuances, but with 47 tools an agent is likely to pick the wrong one.

    Naming Consistency3/5

    Most tools use snake_case verb_noun forms (list_heroes, get_hero, search_game_data), but many are noun-phrase or bare names (hero_stats_calc, tier_list, related, gacha_odds), and similar operations get inconsistent names (get_game_table vs system_lookup vs get_system). The naming is readable but does not reliably signal each tool's role.

    Tool Count2/5

    47 tools is well beyond the practical upper bound and is padded with near-duplicates that could be merged into parameterized endpoints (hero record, item lookup, search). A broad game-data domain can justify many tools, but this count creates maintenance and selection overhead.

    Completeness4/5

    The surface is unusually complete: heroes, skills, items, gacha, game tables, build recommendation/validation, and combat math are all covered, with search/refresh paths to avoid dead ends. Minor workarounds remain (no direct list_skills/list_items, and simulate_fight omits skills/energy), but agents can still accomplish the core workflows.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mlbb-mcp

      cebarrett
      F
      license
      Not graded
      quality
      D
      maintenance
      Enables querying Mobile Legends: Bang Bang hero data including win rates, counters, synergies, and builds via natural language.
      -

    • pokemon-mcp

      suirenn0627
      A
      license
      A
      quality
      C
      maintenance
      Provides accurate Pokemon data and Gen 9 damage calculation tools including stats, moves, type effectiveness, damage calculations, and accuracy checks for Pokemon battles.
      8
      MIT