@cyanheads/pokeapi-mcp-server
Look up Pokémon, moves, abilities, items, natures, and type matchups from PokéAPI v2 via MCP. STDIO or Streamable HTTP.
7 Tools • 2 Resources • 1 Prompt
Overview
Pokémon game data from PokéAPI: Pokémon, moves, abilities, items, and natures. Get a complete Pokémon profile in one call (stats, abilities, evolution, sprites), filter by generation, type, pokédex, or egg group, and compute dual-type matchups.
Tools
Resources
All resource data is also reachable via tools.
Prompt
Request pokeapi_team_builder through your client's prompt picker with required arguments lead, opponent, and opponent_kind (pokemon or type). For example, the MCP prompts/get parameters are:
For a type opponent, use "opponent": "electric", "opponent_kind": "type". Retrieval returns instructions; the client then calls the existing tools to propose up to six verified members including the lead. The workflow asks for game/format restrictions and separates type-chart and base-stat observations from recommendations. It does not establish battle turn order, game legality, or guaranteed counters; a type opponent has no individual Speed.
Capability reference
pokeapi_get_pokemon tool
- Accepts a name (including display spellings such as
Mr. Mime) or numeric PokéAPI Pokémon-record ID as identifier; an unknown entry returns not_found. A species name resolves to its default variety (deoxys returns deoxys-normal, with resolvedFromSpecies: "deoxys").
- Returns stats, types, ability effects, sprites, evolution chain (every
evolutionDetails alternative), varieties, capture and growth rates, gender ratio, and legendary/mythical flags in one dossier.
id preserves Pokémon-record identity, including forms. speciesId is the National Pokédex number; pokedexNumbers lists Pokédex entries as { pokedex, entryNumber }. Breeding data includes nullable hatchCounter and baseHappiness, plus isBaby. Alolan Raichu keeps record ID 10100 while reporting species ID 26.
include_moves (default false) adds each move's learn methods, levels, and versionGroup, selecting the latest group per move and method by PokéAPI's chronology. Distinct levels within that group are retained. moveCount always counts distinct moves across all groups.
version_group (such as scarlet-violet) implies move inclusion and selects that group's recorded methods and levels. A known group with no moves returns an empty list and a notice; an unknown group returns invalid_version_group. If default-summary chronology metadata is unavailable, a notice identifies the fallback to each move and method's last group in source order.
game_version selects English flavor text independently of moves. flavorTextVersion names its source. A missing match, including an unknown version, keeps the successful dossier and reports the fallback to the last English entry in PokéAPI source order. Both text fields are null when no English entry exists.
pokeapi_get_type_matchups tool
- Requires exactly one of
type (type name) or pokemon (name or PokéAPI Pokémon-record ID); unknown entries return not_found.
- Species names resolve to their default variety (
deoxys uses deoxys-normal); resolvedPokemon and resolvedFromSpecies report the match and are null for direct type queries.
- Returns
offensiveRelations (null for dual-type Pokémon) and defensiveMatchups, with dual-type defenses composed and immunity taking precedence.
composedMultipliers carries 0, 0.25, 0.5, 1, 2, or 4 per attacking type; absent types also deal 1×.
pokeapi_get_move tool
- Accepts a move name (such as
King’s Shield) or numeric ID; an unknown entry returns not_found.
- Returns type, damage class, power, accuracy, PP, priority, target, stat changes, and secondary-effect chance, plus full and short English effect text
include_learners (default false) adds the list of Pokémon that can learn the move. learnersIncluded distinguishes an unrequested list from a requested list with no known learners.
pokeapi_get_ability tool
- Accepts an ability name or numeric ID
- Returns full and short English effect text, the generation introduced, and every Pokémon that has the ability, with its hidden-ability flag and slot
not_found when the identifier resolves to no ability
pokeapi_get_item tool
- Accepts an item name (such as
Poké Ball) or numeric ID
- Returns category, fling power, attributes (holdable, consumable, etc.), sprite URL, effect text, and Pokémon that commonly hold it
prices lists every version/currency row (versionGroup, currency, purchasePrice, sellPrice); null means not purchasable/sellable there, and an empty list means no price records. cost is the legacy Pokédollar cost, or null.
not_found when the identifier resolves to no item
pokeapi_get_nature tool
identifier (name or ID 1–25) is optional — omit it to return all 25 natures at once (isListAll: true)
- Each entry carries the boosted stat, reduced stat, and liked/disliked berry flavor — all null for the 5 neutral natures
not_found when a provided identifier resolves to no nature
pokeapi_find_pokemon tool
- Requires at least one of
generation, type, pokedex, and egg_group, combined with AND logic; query (at most 100 characters) adds per-token name matching within them. An invalid_filter error names the failed filter and lists its accepted names when the catalog is available.
- Egg groups accept in-game names such as
Field, Water 1, and Amorphous; appliedFilters reports their canonical PokéAPI names. Regions with multiple dexes need a specific pokedex, such as original-sinnoh or extended-sinnoh.
- Returns
id and name entries for follow-up pokeapi_get_pokemon calls, with totalCount before paging. Type-only searches include forms; generation, pokédex, and egg-group filters return species. A pokedex filter also returns each species' regional entryNumber and sorts by that number before paging, including mixed-filter searches. Searches without a dex retain PokéAPI ID order.
appliedFilters echoes the filters, query tokens, limit, and offset that were applied. A call with no category returns no entries and a notice saying one is required.
limit (default 50) and offset (default 0) paginate the filtered set. A page past the last match keeps totalCount and advises offset: 0; zero matches advise relaxing the filters.
pokeapi://pokemon/{identifier} resource
- Same payload as
pokeapi_get_pokemon with include_moves fixed to false
identifier is a name or PokéAPI Pokémon-record ID, including form IDs; a species name resolves to its default variety. URI variables are percent-decoded once: pokeapi://pokemon/mr%2Dmime resolves to Mr. Mime. Malformed escapes return a validation error; double-encoded values remain misses
not_found when the identifier matches no Pokémon record and no species
pokeapi://type/{typeName} resource
- Returns the raw offensive and defensive damage-relation multiplier table for one type
typeName is a PokéAPI type name; URI variables are percent-decoded once, so pokeapi://type/f%69re resolves to Fire
not_found when the type name doesn't exist in PokéAPI
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
PokéAPI-specific:
- Keyless and read-only — no API key, no auth, no configuration required to run
- Graph-walk consolidation —
pokeapi_get_pokemon fans out across /pokemon, /pokemon-species, /evolution-chain, and N /ability endpoints in two parallel tiers, returning one object
- Aggressive caching — PokéAPI data is static game data; responses are cached with a configurable TTL (default 6 h) to respect PokéAPI's fair-use policy
- Input normalization — folds display names by lowercasing, removing diacritics, apostrophes, periods, and colons, mapping
♀/♂ to -f/-m, and hyphenating whitespace. The result must contain only letters a–z, digits, or hyphens and fit within 100 characters. Invalid identifiers return not_found without a record request; an invalid search filter returns invalid_filter and may fetch its separate vocabulary for recovery
- English-first —
effect_entries and flavor_text_entries are always filtered to language.name === 'en'; absent entries surface as null rather than a foreign-language string
Agent-friendly output:
- Dual-type composition —
pokeapi_get_type_matchups computes the effective matchup matrix from raw damage relations, so agents get a direct answer rather than raw tables to multiply
- Variant surface —
pokeapi_get_pokemon lists all form variants so agents can identify and re-call with specific forms (Alolan, Galarian, Mega, Gigantamax)
- Nullable details — missing descriptions, sprites, holders, and learners are stated explicitly in text and structured results rather than omitted
Getting started
Connect to the hosted instance, no install:
Or run it locally:
For other clients, add this to the MCP config file:
No API key is required. For Docker or a source build, see Running the server.
Configuration
See .env.example for the full list of optional overrides.
Self-hosting for high-volume use
PokéAPI's Fair Use Policy asks consumers to cache aggressively and points high-volume deployments toward running a local instance. This server already caches responses for 6 hours by default (POKEAPI_CACHE_TTL_SECONDS), which covers most workloads. For hosted or batch-heavy deployments, run the official PokéAPI Docker image locally and point POKEAPI_BASE_URL at it — the server switches transparently.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+).
-
Build and run:
-
Run checks and tests:
Docker
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/pokeapi-mcp-server. For stdio, run docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/pokeapi-mcp-server:latest. To build locally, run docker build -t pokeapi-mcp-server .; add --build-arg OTEL_ENABLED=false to omit OpenTelemetry peer dependencies.
Project structure
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — catch typed upstream errors only to map a declared
errors[] contract with ctx.fail(...)
- Use
ctx.log for request-scoped logging, ctx.state for tenant-scoped storage (and caching)
- Register new tools, resources, and prompts in the
createApp() arrays in src/index.ts
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.