Pokémon Champions MCP 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

Related MCP server: Pokemon Showdown MCP Server

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

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)