Pokémon Battle Helper MCP Server

A TypeScript MCP server for Pokémon Champions battle assistance.

For the canonical design, data sources, battle model, tool schemas, solver behavior, and test strategy, see Architecture.md.

Tools

The server registers these MCP tools:

• get_meta_snapshot
• get_pokemon_options
• calculate_stats
• check_damage_matchup
• optimize_offensive_spread
• optimize_survival_spread
• optimize_speed_spread
• get_speed_tiers

All tools expose input/output schemas through MCP tools/list.

Install / build / test

npm install
npm run build
npm test

npm test runs a pretest build and includes MCP stdio e2e tests that start dist/index.js, connect with the real @modelcontextprotocol/sdk client, call tools, and verify tool schemas.

Run as an MCP server

npm run build
node dist/index.js

Example MCP client config:

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

Live meta defaults

The implementation uses Pikalytics English live data for the current Pokémon Champions ranked ladder. Default meta URL shape:

https://www.pikalytics.com/api/p/2026-05/battledataregmbs3-1760
https://www.pikalytics.com/api/p/2026-05/battledataregmbs3-1760/garchomp

get_meta_snapshot and get_pokemon_options accept optional format request fields (single/double; default double). Pikalytics' battledataregmbs3 key is the Champions doubles ladder, so format currently does not change the queried dataset. The season/regulation key (battledataregmbs3) and rating cutoff (1760) are internal constants; update them when the live regulation changes. The data month (YYYY-MM) is discovered automatically — a preferred month is tried first, then recent months are probed newest-first — because Pikalytics serves the literal JSON false for months without data.

Pokémon name handling

All tools accept any common spelling of a Pokémon name and normalize it server-side (see src/utils/pokemon-name.ts):

• Showdown forme names and aliases: Basculegion-F, lando-t, Urshifu-Rapid-Strike.
• PokeAPI/Pikalytics-style slugs: basculegion-female, urshifu-rapid-strike.
• Space/punctuation variants: Rotom Wash, Sirfetch'd.

Material corrections (e.g. basculegion-female -> Basculegion-F) are reported in inputCorrections. For get_pokemon_options, a base-species request resolves to the only matching meta forme when unambiguous (Floette -> Floette-Mega, with a formeResolved correction); if several formes are ranked, the tool returns an error listing the candidates. When Pikalytics has no page for the requested forme and base-forme data is used instead, the response carries an explicit warning (formeDataFallback) instead of silently returning the wrong forme's data. Unknown names produce did-you-mean suggestions.

Calc-oriented tool handlers (calculate_stats, check_damage_matchup, and the SP optimizers) also guard against the common LLM mistake of sending a bare base species for a current-format forme request: if the submitted name is a canonical base species and the current meta has exactly one matching forme, the handler rewrites it and reports formeResolved in inputCorrections before doing the calculation. Ambiguous cases still require the client/model to specify the forme.

Recommended client/system instruction:

For Pokémon Champions build, Mega, forme, damage, or speed questions, call get_pokemon_options
first for each named Pokémon and use the returned canonical Pokémon name/build in calculator
tools. Do not guess a base species when the user requested a Mega or forme. Item choices should
be passed exactly as provided by the user; this MCP does not validate item legality.

Mega forme ability handling

When a request uses a Mega forme, the server canonicalizes stale or missing abilities to the fixed Mega ability before calculation and reports the change in inputCorrections plus modifierBreakdown. get_pokemon_options also returns the Mega ability for Mega forme requests, even when move/item/spread data has to come from a base-form meta page.

If the ability has already been changed in battle by Skill Swap, Worry Seed, Entrainment, etc., clients should send the current effective ability and mark it explicitly with pokemon.abilitySource: "battle-changed" or an active ability-change effect such as { "id": "abilitychanged" }, { "id": "skillswap" }, or { "id": "worryseed" }. For ability suppression such as Gastro Acid, keep the actual ability and use state.abilityEffect: "inactive".