Skip to main content
Glama
@cyanheads/pokeapi-mcp-server

@cyanheads/pokeapi-mcp-server

by cyanheads
README.md
<div align="center">
  <h1>@cyanheads/pokeapi-mcp-server</h1>
  <p><b>Look up Pokémon, moves, abilities, items, natures, and type matchups from PokéAPI v2 via MCP. STDIO or Streamable HTTP.</b>
  <div>7 Tools • 2 Resources • 1 Prompt</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.3.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pokeapi-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pokeapi-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pokeapi-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/pokeapi-mcp-server/releases/latest/download/pokeapi-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=pokeapi-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvcG9rZWFwaS1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22pokeapi-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fpokeapi-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://pokeapi.caseyjhand.com/mcp](https://pokeapi.caseyjhand.com/mcp)

</div>

---

## 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 |
|:-----|:------------|
| `pokeapi_get_pokemon` | Denormalized Pokémon dossier in one call — stats, types, abilities, evolution chain, sprites, and species data |
| `pokeapi_get_type_matchups` | Computed offensive and defensive type effectiveness for a type or Pokémon, with correctly composed dual-type matchups |
| `pokeapi_get_move` | Move details — type, damage class, power, accuracy, PP, priority, stat changes, and effect text |
| `pokeapi_get_ability` | Ability details — effect text and the Pokémon that have it, with hidden-ability flag and slot |
| `pokeapi_get_item` | Item details — effect text, category, versioned prices, fling power, attributes, and common holders |
| `pokeapi_get_nature` | Nature details — stat boost/penalty and berry flavor preferences; lists all 25 when called without an identifier |
| `pokeapi_find_pokemon` | Filter Pokémon by generation, type, pokédex, or egg group, with name-token matching and pagination |

### Resources

| Resource | Description |
|:---|:---|
| `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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- `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` <sub>tool</sub>

- 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}` <sub>resource</sub>

- 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}` <sub>resource</sub>

- 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`](https://github.com/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](#running-the-server).

---

## Configuration

| Variable | Description | Default |
|:---------|:------------|:--------|
| `POKEAPI_BASE_URL` | PokéAPI base URL — override for local mirrors or proxies. | `https://pokeapi.co/api/v2` |
| `POKEAPI_CACHE_TTL_SECONDS` | How long to cache PokéAPI responses (seconds). | `21600` (6 h) |
| `POKEAPI_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds. | `10000` |
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_SESSION_MODE` | HTTP session mode: `auto`, `stateful`, or `stateless`. | `stateless` |
| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
| `LOG_TOOL_FAILURE_PAYLOADS` | Log 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_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP log export endpoint. | Unset |

See [`.env.example`](./.env.example) for the full list of optional overrides.

### Self-hosting for high-volume use

PokéAPI's [Fair Use Policy](https://pokeapi.co/docs/v2#fairuse) 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](https://github.com/PokeAPI/pokeapi) locally and point `POKEAPI_BASE_URL` at it — the server switches transparently.

---

## Running the server

### Local development

Requires [Bun v1.4.4](https://bun.sh/) or higher (or Node.js v24+).

```sh
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 required
```

- **Build and run:**

  ```sh
  bun run rebuild

  bun run start:stdio
  # or
  bun run start:http
  ```

- **Run checks and tests:**

  ```sh
  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

```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

| Path | Purpose |
|:-----|:--------|
| `src/index.ts` | `createApp()` 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`](./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 devcheck
bun run test
```

---

## License

Apache-2.0 — see [LICENSE](LICENSE) for details.