random-pokemon-mcp
Offline TypeScript MCP server using @modelcontextprotocol/sdk and stdio. Node.js >=20. No backend, keys, telemetry or runtime API requests. Companion website: https://random-pokemon-generator.org
0.2.0 changelog: added real abilities (including hidden flags), independent legendary/mythical filtering, and learnable damaging-move type coverage from an offline PokeAPI snapshot. National Dex 1–1025, bundled English names, default forms only. Generation filters mean introduction generation; matchups use Gen VI+ types.
两种使用方式，让用户自己选
- 本地版（stdio）：使用下方
npx -y random-pokemon-mcp@0.2.0安装配置；数据随包离线提供，无需 API 密钥。 - 托管版（网站 Worker）：支持远程 MCP 的客户端可使用
https://random-pokemon-generator.org/api/mcp，无需本地安装。托管服务独立开发、部署与更新，功能和数据版本可能与本地版不同。
Install and configure
After the package is manually published, run npx -y random-pokemon-mcp@0.2.0. Before publication use npm ci && npm run build, then configure node /absolute/path/random-pokemon-mcp/dist/index.js.
Claude Code:
claude mcp add random-pokemon -- npx -y random-pokemon-mcp@0.2.0
Cursor (.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json):
{"mcpServers":{"random-pokemon":{"command":"npx","args":["-y","random-pokemon-mcp@0.2.0"]}}}
VS Code (.vscode/mcp.json):
{"servers":{"random-pokemon":{"type":"stdio","command":"npx","args":["-y","random-pokemon-mcp@0.2.0"]}}}
On Windows use npx.cmd if required by the client. stdout contains MCP protocol only.
Exactly five tools
| Tool | Input and behavior |
|---|---|
get_pokemon |
pokemon: English name or numeric National Dex ID. Types, base stats, generation, URL-only artwork, real abilities with is_hidden/slot, and is_legendary/is_mythical. |
get_type_effectiveness |
Optional attacking and/or defending (1–2 distinct lowercase English types); at least one required. Attack groups, defense groups and product when both supplied. |
random_team |
seed string (default random-pokemon), optional generations 1–9 and any-matching types; six distinct species, per-member defensive groups and exact 2x/4x team counts. includeLegendary and includeMythical default true; false independently excludes that category. Existing parameter names/defaults remain compatible; false now succeeds instead of returning the 0.1.0 missing-data error. Unlike the website’s combined legendary/mythical set, these are separate PokeAPI classifications; disabling legendary alone still permits mythical species and vice versa. |
analyze_team |
text: 1–6 Showdown sets separated by blank lines, including nicknames. Defensive groups, team counts, learnable damaging-move type coverage against single types, descending base-speed tiers and explicit unknown-role evidence. Submitted moves are echoed but are not used to calculate coverage or legality checked. Coverage unions every non-status move in the default form’s PokeAPI learnset across all version groups. It describes potential options, not a simultaneous four-move set; it does not guarantee availability in a particular game, generation or format. Dynamic move-type mechanics are not modeled. No scores or rankings. EVs, IVs, level, nature, items and abilities in text are not simulated. |
calc_damage |
Required attacker, defender, moveType, power (1–300), category (physical/special). Optional level (default 50), attack/defense objects (iv 31, ev 0, nature neutral/boosted/hindered, stage 0), hpIV 31, hpEV 0, currentHP full. Simplified regular base-damage formula, STAB and typing, 85–100% rolls; min/max HP and percentages, possible/guaranteed OHKO thresholds. User supplies move facts; no move database or EV-total legality checking. |
Damage description and every success/error declare 未计入项：天气/场地/道具/特性/太晶、暴击、烧伤、墙、双打修正、特殊招式机制及逐步定点舍入. Estimates can differ from cartridge mechanics; this is not a battle simulator. Immunities yield zero damage. Shedinja's base HP rule is handled. No TCG, GO or Nuzlocke scope.
Data provenance
Base facts come from the companion site's local libs/pokemon/data/pokemon.json (1025 records: names, types, stats, introduction generation and image URLs). src/type-chart.ts retains its 18×18 Gen VI+ chart. Original source-byte hashes remain in data/source-sha256.json.
Additional snapshot: PokeAPI, fetched 2026-10-26, covering default Pokémon IDs 1–1025 through https://pokeapi.co/api/v2/pokemon/{id} and https://pokeapi.co/api/v2/pokemon-species/{id}. Referenced /api/v2/move/{id} responses supply type and damage class. data/pokeapi.json stores only abilities, separate classification flags and a sorted set of learnable non-status move types per species, plus provenance. Response SHA-256 hashes are in data/pokeapi-sha256.json. No move names/individual learnsets/version details are bundled: this keeps the package small but cannot validate submitted moves, game legality or infer battle roles. Roles remain explicitly unknown.
Reproduce with Python 3 + requests installed, then python3 scripts/snapshot-pokeapi.py [cache-directory] (default cache /tmp/random-pokemon-pokeapi-cache). Three workers, 200ms pause per request, up to five attempts with exponential backoff, cached raw responses and fail-on-error; output files are written only after every required response succeeds. Keep the cache for raw-data audits; it is excluded from npm. Runtime never calls PokeAPI. No image files are fetched or bundled; artwork stays URL-only. Pokémon names/artwork remain the property of their respective owners. MIT covers this project's code; no ownership of third-party Pokémon material is asserted.
Development and verification
npm ci
npm run build
npm run smoke
npm pack --dry-run --json > pack-dry-run.json
node scripts/validate-package.mjs
Smoke invokes the MCP Inspector CLI for tools/list and each tool, plus the SDK client for successful calls to all five tools, invalid inputs and recovery, deterministic seeds, chart/data invariants and damage declarations. Lockfile pins the dependency tree. Inspector is a development dependency only.
Manual release checklist (not executed)
- Review the offline snapshot provenance, limitations and acceptance checks.
- Check npm name ownership, run checks above; manually
npm login, thennpm publish --access publicwhen ready. - Validate
server.jsonagainst the official Registry schema; after npm publication follow official Registry publishing to verifyio.github.yuren-devownership and publish withmcp-publisher. npmmcpNamematches the manifest. - Manually submit/claim GitHub/package details on Glama and mcp.so after checking current submission requirements. No OAuth, registry publishing, directory claim or submission is performed by this repository's scripts.
License: MIT.