PokéMon Champions Server

A small MCP server that gives an AI assistant accurate, up-to-date data for competitive Pokémon Champions. Hook it up to Claude (or any MCP client) and you can ask things like:

"Does my Choice Band Mega Staraptor OHKO Garchomp?" "Is Sneasler legal in Regulation M-B, and who else can run Fake Out there?" "What Fairy moves are usable this format?"

It covers damage calculation, type matchups, Pokédex and item lookups, move search, and regulation legality. Everything runs locally — normal queries never hit the network.

Setup

You'll need Node 18+. Clone the repo, then:

npm install
npm run build

That compiles everything into dist/. Quick check that it works:

npm test

Connecting it to your assistant

This is a standard stdio MCP server, so any MCP client can launch it — you just point it at the built dist/index.js.

1. Grab the absolute path to the entry point (you'll paste this into your client):

   node -e "console.log(require('path').resolve('dist/index.js'))"
   

2. Add it to your client's MCP config:

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

   • Claude Desktop — Settings → Developer → Edit Config, then merge in the block above.
   • Claude Code — claude mcp add pokemon-champions node /absolute/path/dist/index.js.
   • Anything else — add an equivalent stdio entry (command: node, args: [path]).

3. Restart the client. It should now list tools like calculate_damage and find_pokemon_by_move. Try asking it one of the questions up top.

Use the absolute path — the client runs from its own working directory, so a relative one won't resolve.

Hosting it online (Cloudflare Workers)

Want people to use it without installing anything — or from Claude on the web or your phone? Deploy it as a remote HTTP server and they just paste a URL. It runs on Cloudflare Workers' free tier.

Every tool is read-only over public data, so the hosted server is stateless and needs no login or API key — there's no OAuth to set up. Workers has no filesystem, so the datasets are bundled into the Worker (src/worker.ts) instead of read from disk; the local stdio server is untouched.

npm install
npx wrangler login          # one-time: authorize Wrangler with your free Cloudflare account
npm run dev:worker          # optional: test locally (real Workers runtime, no account needed)
npm run deploy:worker       # deploy — prints your public URL

The MCP endpoint is the printed URL plus /mcp (e.g. https://pokemon-champions-mcp.<you>.workers.dev/mcp); a plain GET / is a health check. Add that /mcp URL as a custom connector in Claude (Settings → Connectors; requires a paid plan, or one connector on Free) or as a remote MCP server in Cursor. Config lives in wrangler.toml.

Tools

Tool	What it answers
calculate_damage	"Does my Mystic Water Blastoise OHKO that Garchomp?" — full damage/percent range, hits-to-KO, and the human-readable calc string. Auto-fills stats/typing/ability from the Champions dex (so Mega Staraptor uses Contrary, and even Champions-only Megas like Mega Eelektross calc correctly). Handles items, weather, terrain, Tera, crits, multi-hit, and Doubles spread reduction.
type_effectiveness	The multiplier (0–4x) of an attacking type against 1–2 defending types.
get_pokemon	Base stats, typing, abilities, weight, and full movelist for a Pokémon (Mega forms accepted, e.g. Staraptor-Mega, Mega Staraptor, Mega Raichu X). Pass a regulation id to also get legality and regulation-legal moves.
get_item	Effect, how-to-obtain, and category (Hold Item / Mega Stone / Berry) for a held item, e.g. Choice Scarf, Garchompite, Lum Berry. Pass a regulation id to also check legality.
list_items	Browse the held-item catalog, optionally filtered by category or a nameContains substring (held-only by default; includeNonHeld adds tickets). Pass a regulation id to mark which items are legal.
check_legality	Whether a Pokémon — and optionally listed moves and/or held items — is legal in a regulation.
find_pokemon_by_move	"Who can run Fake Out in M-B?" — every Pokémon legal in a regulation that can learn a given move, with the move's type/category/base power. Name-tolerant (willowisp → Will-O-Wisp). Defaults to m-b.
list_legal_moves	The pool of moves usable in a regulation (everything learnable by at least one legal Pokémon), each with type, category, base power, and how many Pokémon learn it. Filter by type, category, or a nameContains substring. Defaults to m-b.
list_legal_pokemon	The regulation's legal roster, each with its dex number, typing, base stats, and abilities. Filter by type (e.g. Dragon) or a nameContains substring. The complement to list_legal_moves. Defaults to m-b.
list_regulations	Which regulations are available locally, with each one's metadata and counts.

Good to know

A few things that reflect how the format actually works, and which the tools tell you about in their output rather than hiding:

• There are no per-move bans. A move is "legal" if a legal Pokémon can learn it, so list_legal_moves is really the pool of learnable moves — and a move with no legal learners (e.g. Spore in M-B) shows up as unusable.
• Mega legality follows the base species. check_legality("Mega Staraptor") resolves via Staraptor, unless that specific Mega is separately excluded (M-B drops Mega Garchomp Z and Mega Lucario Z).
• A handful of Champions-original ability effects aren't simulated. Stats, typing, and the ability name are accurate, but a brand-new ability's special mechanic may not factor into the damage number.

Refreshing the data

The server only ever reads its data files; the scrapers below are run by hand when the game changes. They pull from Serebii.

npm run scrape -- m-b      # regulation legality (roster + bans + legal items)
npm run scrape:items       # held-item catalog (effects, locations, categories)
npm run scrape:dex         # per-Pokémon stats, typing, abilities, learnsets

Pass a different id to the first one for future regulations (npm run scrape -- m-c). The scrapers are deliberately forgiving — if a page changes shape they warn and write what they found instead of crashing.

Layout

src/server.ts       the 9 MCP tools (transport-agnostic; no Node-only or filesystem code)
src/index.ts        stdio entry — mounts server.ts on stdio (the local default)
src/worker.ts       Cloudflare Workers entry — mounts server.ts on HTTP, with data bundled in
src/diskdata.ts     Node-only: reads the JSON datasets from disk and registers them (stdio)
src/calc.ts         damage formula + type effectiveness
src/dex.ts          Pokémon lookups (data/champions-dex.json; injected or disk-loaded)
src/items.ts        item lookups (data/champions-items.json; injected or disk-loaded)
src/movedex.ts      move search, regulation-scoped
src/regulations.ts  legality checks over regulations/*.json (injected or disk-loaded)
src/names.ts        Pokémon-name normalization (Mega word order, base species)
scripts/            the standalone scrapers
data/, regulations/ generated data (committed; bundled into the Worker)
test/smoke.ts       in-memory MCP client exercising every tool
wrangler.toml       Cloudflare Workers config (hosted deployment)