@cyanheads/pokeapi-mcp-server
Public Hosted Server: https://pokeapi.caseyjhand.com/mcp
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
Tool | Description |
| Denormalized Pokémon dossier in one call — stats, types, abilities, evolution chain, sprites, and species data |
| Computed offensive and defensive type effectiveness for a type or Pokémon, with correctly composed dual-type matchups |
| Move details — type, damage class, power, accuracy, PP, priority, stat changes, and effect text |
| Ability details — effect text and the Pokémon that have it, with hidden-ability flag and slot |
| Item details — effect text, category, versioned prices, fling power, attributes, and common holders |
| Nature details — stat boost/penalty and berry flavor preferences; lists all 25 when called without an identifier |
| Filter Pokémon by generation, type, pokédex, or egg group, with name-token matching and pagination |
Resources
Resource | Description |
| Pokémon dossier by name or PokéAPI Pokémon-record ID — same payload as |
| Type damage relations — raw multiplier table, offensive and defensive |
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:
{
"name": "pokeapi_team_builder",
"arguments": { "lead": "charizard", "opponent": "aerodactyl", "opponent_kind": "pokemon" }
}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.
Related MCP server: dexMCP
Capability reference
pokeapi_get_pokemon tool
Accepts a name (including display spellings such as
Mr. Mime) or numeric PokéAPI Pokémon-record ID asidentifier; an unknown entry returnsnot_found. A species name resolves to its default variety (deoxysreturnsdeoxys-normal, withresolvedFromSpecies: "deoxys").Returns stats, types, ability effects, sprites, evolution chain (every
evolutionDetailsalternative), varieties, capture and growth rates, gender ratio, and legendary/mythical flags in one dossier.idpreserves Pokémon-record identity, including forms.speciesIdis the National Pokédex number;pokedexNumberslists Pokédex entries as{ pokedex, entryNumber }. Breeding data includes nullablehatchCounterandbaseHappiness, plusisBaby. Alolan Raichu keeps record ID 10100 while reporting species ID 26.include_moves(defaultfalse) adds each move's learn methods, levels, andversionGroup, selecting the latest group per move and method by PokéAPI's chronology. Distinct levels within that group are retained.moveCountalways counts distinct moves across all groups.version_group(such asscarlet-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 returnsinvalid_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_versionselects English flavor text independently of moves.flavorTextVersionnames 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) orpokemon(name or PokéAPI Pokémon-record ID); unknown entries returnnot_found.Species names resolve to their default variety (
deoxysusesdeoxys-normal);resolvedPokemonandresolvedFromSpeciesreport the match and are null for direct type queries.Returns
offensiveRelations(null for dual-type Pokémon) anddefensiveMatchups, with dual-type defenses composed and immunity taking precedence.composedMultiplierscarries 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 returnsnot_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(defaultfalse) adds the list of Pokémon that can learn the move.learnersIncludeddistinguishes 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_foundwhen the identifier resolves to no ability
pokeapi_get_item tool
Accepts an item name (such as
Poké Ball) or numeric IDReturns category, fling power, attributes (holdable, consumable, etc.), sprite URL, effect text, and Pokémon that commonly hold it
priceslists every version/currency row (versionGroup,currency,purchasePrice,sellPrice); null means not purchasable/sellable there, and an empty list means no price records.costis the legacy Pokédollar cost, or null.not_foundwhen 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_foundwhen a provided identifier resolves to no nature
pokeapi_find_pokemon tool
Requires at least one of
generation,type,pokedex, andegg_group, combined with AND logic;query(at most 100 characters) adds per-token name matching within them. Aninvalid_filtererror 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, andAmorphous;appliedFiltersreports their canonical PokéAPI names. Regions with multiple dexes need a specificpokedex, such asoriginal-sinnohorextended-sinnoh.Returns
idandnameentries for follow-uppokeapi_get_pokemoncalls, withtotalCountbefore paging. Type-only searches include forms; generation, pokédex, and egg-group filters return species. Apokedexfilter also returns each species' regionalentryNumberand sorts by that number before paging, including mixed-filter searches. Searches without a dex retain PokéAPI ID order.appliedFiltersechoes the filters, query tokens,limit, andoffsetthat were applied. A call with no category returns no entries and a notice saying one is required.limit(default 50) andoffset(default 0) paginate the filtered set. A page past the last match keepstotalCountand advisesoffset: 0; zero matches advise relaxing the filters.
pokeapi://pokemon/{identifier} resource
Same payload as
pokeapi_get_pokemonwithinclude_movesfixed tofalseidentifieris 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%2Dmimeresolves to Mr. Mime. Malformed escapes return a validation error; double-encoded values remain missesnot_foundwhen 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
typeNameis a PokéAPI type name; URI variables are percent-decoded once, sopokeapi://type/f%69reresolves to Firenot_foundwhen 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_pokemonfans out across/pokemon,/pokemon-species,/evolution-chain, and N/abilityendpoints in two parallel tiers, returning one objectAggressive 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 lettersa–z, digits, or hyphens and fit within 100 characters. Invalid identifiers returnnot_foundwithout a record request; an invalid search filter returnsinvalid_filterand may fetch its separate vocabulary for recoveryEnglish-first —
effect_entriesandflavor_text_entriesare always filtered tolanguage.name === 'en'; absent entries surface asnullrather than a foreign-language string
Agent-friendly output:
Dual-type composition —
pokeapi_get_type_matchupscomputes the effective matchup matrix from raw damage relations, so agents get a direct answer rather than raw tables to multiplyVariant surface —
pokeapi_get_pokemonlists 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:
claude mcp add --transport http pokeapi-mcp-server https://pokeapi.caseyjhand.com/mcpOr run it locally:
claude mcp add pokeapi-mcp-server -- npx -y @cyanheads/pokeapi-mcp-serverFor other clients, add this to the MCP config file:
{
"mcpServers": {
"pokeapi-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/pokeapi-mcp-server"]
}
}
}No API key is required. For Docker or a source build, see Running the server.
Configuration
Variable | Description | Default |
| PokéAPI base URL — override for local mirrors or proxies. |
|
| How long to cache PokéAPI responses (seconds). |
|
| Per-request timeout in milliseconds. |
|
| Transport: |
|
| HTTP session mode: |
|
| Port for HTTP server. |
|
| Auth mode: |
|
| Log level (RFC 5424). |
|
| Directory for log files (Node.js only). |
|
| Log failed-call input and result, redacted by key name and capped at |
|
| Enable OpenTelemetry instrumentation. |
|
| OTLP log export endpoint. | Unset |
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+).
git clone https://github.com/cyanheads/pokeapi-mcp-server.git
cd pokeapi-mcp-server && bun install
cp .env.example .env # optional overrides; no API key requiredBuild and run:
bun run rebuild bun run start:stdio # or bun run start:httpRun checks and tests:
bun run devcheck # Lint, format, typecheck, security bun run test # Offline Vitest suite with deterministic fetch fixtures bun run lint:mcp # Validate MCP definitions against spec
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/pokeapi-mcp-server:latestThe 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
Path | Purpose |
|
|
| Server-specific env var parsing with Zod ( |
| Tool definitions ( |
| Resource definitions ( |
| Pure prompt templates ( |
|
|
| Vitest test suite mirroring |
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 withctx.fail(...)Use
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storage (and caching)Register new tools, resources, and prompts in the
createApp()arrays insrc/index.tsWrap 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:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Pokemon MCP — wraps PokéAPI (free, no auth required)
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
Search NPPES providers and resolve NUCC specialty codes via MCP over STDIO or Streamable HTTP.
Provide detailed Pokémon data and information through a standardized MCP interface. Enable LLMs an…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that interfaces with PokeAPI to provide Pokémon information to LLM applications through JSON-RPC over stdio.ISC
- AlicenseAqualityCmaintenanceA Model Context Protocol server that wraps pypokedex to provide Pokemon data tools for MCP-compatible applications.101MIT
- AlicenseNot gradedqualityDmaintenanceMCP server providing tools to look up Pokémon, moves, abilities, items, locations, evolutions, and more from the PokéAPI via natural language.72 npm2ISC
- AlicenseNot gradedqualityBmaintenanceLook up countries, timezones, periodic table elements, physical constants, units, HTTP status codes, and MIME types via MCP. STDIO or Streamable HTTP.306 npm1Apache 2.0