Pokeapi Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.3.1Updated Nov 11, 2026

Look up Pokémon, moves, abilities, items, natures, and type matchups from PokéAPI v2.

VerifiedStreamable HTTPWeb executable

Overview

AI-generated overview

Looks up Pokémon, moves, abilities, items, natures and type matchups from PokéAPI v2, returning consolidated dossiers and computed effectiveness.

What you can do
  • Fetch a full Pokémon dossier: stats, types, abilities, evolution chain, sprites, species data, optional move lists
  • Compute offensive and defensive type effectiveness for a type or Pokémon, with dual-type multipliers composed
  • Look up moves, abilities, items and natures, including effect text, learners, holders and stat changes
  • Filter Pokémon by generation, type, regional Pokédex or egg group, with name matching and pagination
  • Read Pokémon and type context through two resources, and request a team-builder prompt
When to use it
Useful when you want an assistant to answer Pokémon questions, compare type matchups, or help with competitive team building without manually consulting PokéAPI. It is a read-only reference source, so it suits casual lookups and drafting, not authoritative legality or battle-order rulings.
Requirements
Either the hosted HTTP endpoint or a local process via npx (Node.js; Bun 1.4.4+ or Node.js 24+ for a source build). No API key or account is needed. Optional environment variables cover the PokéAPI base URL, cache TTL, request timeout, transport, HTTP port, auth mode and logging.
Before you install
Read-only and keyless, with no writes or payments. If you enable MCP_AUTH_MODE jwt or oauth on a self-hosted instance, you supply the credentials yourself. LOG_TOOL_FAILURE_PAYLOADS can log failed-call inputs and results, and secrets inside free-form values are not redacted. Requests go to PokéAPI or the configured POKEAPI_BASE_URL.

Installation

In SourceWeft

  1. Open Pokeapi Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fpokeapi-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "pokeapi": {
      "type": "http",
      "url": "https://pokeapi.caseyjhand.com/mcp"
    }
  }
}

README

@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

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

ToolDescription
pokeapi_get_pokemonDenormalized Pokémon dossier in one call — stats, types, abilities, evolution chain, sprites, and species data
pokeapi_get_type_matchupsComputed offensive and defensive type effectiveness for a type or Pokémon, with correctly composed dual-type matchups
pokeapi_get_moveMove details — type, damage class, power, accuracy, PP, priority, stat changes, and effect text
pokeapi_get_abilityAbility details — effect text and the Pokémon that have it, with hidden-ability flag and slot
pokeapi_get_itemItem details — effect text, category, versioned prices, fling power, attributes, and common holders
pokeapi_get_natureNature details — stat boost/penalty and berry flavor preferences; lists all 25 when called without an identifier
pokeapi_find_pokemonFilter Pokémon by generation, type, pokédex, or egg group, with name-token matching and pagination

Resources

ResourceDescription
pokeapi://pokemon/{identifier}Pokémon dossier by name or PokéAPI Pokémon-record ID — same payload as pokeapi_get_pokemon without moves
pokeapi://type/{typeName}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:

json
{  "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.


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:

sh
claude mcp add --transport http pokeapi-mcp-server https://pokeapi.caseyjhand.com/mcp

Or run it locally:

sh
claude mcp add pokeapi-mcp-server -- npx -y @cyanheads/pokeapi-mcp-server

For other clients, add this to the MCP config file:

json
{  "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

VariableDescriptionDefault
POKEAPI_BASE_URLPokéAPI base URL — override for local mirrors or proxies.https://pokeapi.co/api/v2
POKEAPI_CACHE_TTL_SECONDSHow long to cache PokéAPI responses (seconds).21600 (6 h)
POKEAPI_REQUEST_TIMEOUT_MSPer-request timeout in milliseconds.10000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_SESSION_MODEHTTP session mode: auto, stateful, or stateless.stateless
MCP_HTTP_PORTPort for HTTP server.3010
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADSLog failed-call input and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). Secrets inside free-form values are not redacted.false
OTEL_ENABLEDEnable OpenTelemetry instrumentation.false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTLP 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+).

sh
git clone https://github.com/cyanheads/pokeapi-mcp-server.gitcd pokeapi-mcp-server && bun installcp .env.example .env   # optional overrides; no API key required
  • Build and run:

    sh
    bun run rebuild
    bun run start:stdio# orbun run start:http
  • Run checks and tests:

    sh
    bun run devcheck   # Lint, format, typecheck, securitybun run test       # Offline Vitest suite with deterministic fetch fixturesbun run lint:mcp   # Validate MCP definitions against spec

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/pokeapi-mcp-server:latest

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

PathPurpose
src/index.tscreateApp() entry point — registers tools, resources, prompts, and inits services.
src/config/Server-specific env var parsing with Zod (server-config.ts).
src/mcp-server/tools/Tool definitions (*.tool.ts).
src/mcp-server/resources/Resource definitions (*.resource.ts).
src/mcp-server/prompts/Pure prompt templates (*.prompt.ts).
src/services/pokeapi/PokeApiService — typed fetch methods, caching, retry, timeout.
tests/Vitest test suite mirroring src/.

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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

Source: README.md at commit 319159d

Tools

7

pokeapi_get_pokemon

Get Pokémon

Get a fully denormalized Pokémon dossier in a single call — base stats, types, abilities (with full English effect text), height/weight, resolved evolution chain, sprite URLs including official artwork, species flavor text, variety list, capture rate, growth rate, gender rate, legendary/mythical flags, egg groups, and (optionally) a summarized learnable-move list. Accepts a Pokémon name (e.g. "bulbasaur", "Mr. Mime") or PokéAPI Pokémon-record ID. A species name with no Pokémon record of its own (e.g. "deoxys") resolves to the default variety of that species ("deoxys-normal"), reported in resolvedFromSpecies. Set include_moves=true to include the move summary (large); defaults to false. Use game_version to select flavor text from a specific game (e.g. "sword", "red"); falls back to the last English entry in PokéAPI source order when no English entry matches. Use pokeapi_find_pokemon to discover Pokémon by type, generation, or egg group before calling this tool.

Parametersidentifierrequiredgame_versioninclude_movesversion_group

pokeapi_get_type_matchups

Get Type Matchups

Get the full offensive and defensive type effectiveness breakdown. Provide either a type name (e.g. "fire", "psychic") or a Pokémon identifier (name or PokéAPI Pokémon-record ID; a species name resolves to its default variety). For dual-type Pokémon, the defensive multipliers are correctly composed (e.g. Fire/Flying vs Rock = 4× because both types are weak to Rock). Exactly one of type or pokemon must be provided.

Parameterstypepokemon

pokeapi_get_move

Get Move

Get move details by name or numeric ID — type, damage class, power, accuracy, PP, priority, target, stat changes, status-effect chance, and full English effect text. Set include_learners=true to include the list of Pokémon that can learn the move. Move names are available from pokeapi_get_pokemon when include_moves=true.

Parametersidentifierrequiredinclude_learners

pokeapi_get_ability

Get Ability

Get ability details by name or numeric ID — full English effect text, short effect text, generation introduced, and the list of Pokémon that have the ability (including hidden-ability flag and slot). Ability names are returned by pokeapi_get_pokemon in the abilities array.

Parametersidentifierrequired

pokeapi_get_item

Get Item

Get item details by name or numeric ID — effect text, category, versioned purchase and sell prices, fling power, item attributes (holdable, consumable, etc.), sprite URL, and Pokémon that commonly hold it.

Parametersidentifierrequired

pokeapi_get_nature

Get Nature

Get nature details — the stat boosted (+10%), stat reduced (-10%), and preferred/disliked berry flavors. Omit the identifier to list all 25 natures at once. Natures are critical for competitive team-building: every non-neutral nature modifies two stats by ±10%.

Parametersidentifier

pokeapi_find_pokemon

Find Pokémon

Filter Pokémon by generation, type, regional pokédex, or egg group. Returns names and PokéAPI IDs; every returned name works as a pokeapi_get_pokemon identifier, where a species name resolves to its default variety. Pokédex searches include regional entry numbers and sort by those numbers before pagination. At least one of generation, type, pokedex, or egg_group is required; the ones provided are combined with AND logic, and query adds strict token matching on name within them. A call with no category filter, with or without query, returns an empty result and a notice naming the requirement.

Parameterstypelimitqueryoffsetpokedexegg_groupgeneration

Version history

6
  1. v0.3.1LatestNov 11, 2026
  2. v0.3.0Oct 30, 2026
  3. v0.2.1Oct 14, 2026
  4. v0.2.0Sep 30, 2026
  5. v0.1.9Sep 19, 2026
  6. v0.1.8Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts