pokemcp

A Model Context Protocol (MCP) server that exposes the PokéAPI as tools and resources, letting any MCP-compatible AI assistant look up Pokémon data in real time.

Features

• 22 tools across Pokémon, moves, items, and types
• 8 MCP resources for direct URI-based data access
• Optional Redis caching with a local in-memory fallback
• Automatic retry with exponential back-off on API errors
• Zero configuration required — works out of the box against the public PokéAPI

---

Requirements

• Python ≥ 3.11
• uv package manager

---

Installation

git clone https://github.com/Ragde54/pokemcp.git
cd pokemcp
uv sync

---

Running the server

PYTHONPATH=src uv run pokemcp

Note: The PYTHONPATH=src prefix is required due to a known incompatibility between Homebrew Python's venv and editable-install .pth file processing.

---

Claude Desktop integration

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pokemcp": {
      "command": "uv",
      "args": ["run", "pokemcp"],
      "cwd": "/path/to/pokemcp",
      "env": {
        "PYTHONPATH": "/path/to/pokemcp/src"
      }
    }
  }
}

Replace /path/to/pokemcp with the absolute path to this repository, then restart Claude Desktop.

---

Configuration

Settings are read from environment variables or a .env file in the project root.

Variable	Default	Description
POKEAPI_BASE_URL	https://pokeapi.co/api/v2	PokéAPI base URL
REDIS_URL	(none)	Redis URL for persistent caching (e.g. redis://localhost:6379). If unset, an in-memory cache is used.
CACHE_TTL	3600	Cache time-to-live in seconds
LOG_LEVEL	INFO	Python logging level

---

Tools

🐾 Pokémon

Tool	Description
get_pokemon(name_or_id)	Full Pokémon details: types, stats, abilities, sprites, forms, held items, and more
get_pokemon_species(name_or_id)	Species data: Pokédex flavor text, habitat, generation, legendary/mythical status, gender rate
get_pokemon_stats(name_or_id)	Base stats (HP, Attack, Defense, Sp. Atk, Sp. Def, Speed) plus total BST
get_pokemon_abilities(name_or_id)	All abilities and whether each is a hidden ability
get_evolution_chain(name_or_id)	Full evolution chain with trigger conditions
list_pokemon(limit, offset)	Paginated list of all Pokémon (max 100 per page)
search_pokemon_by_type(type_name)	All Pokémon belonging to a given type

⚔️ Moves

Tool	Description
get_move(name_or_id)	Full move details: type, power, accuracy, PP, damage class, effect, and more
get_move_summary(name_or_id)	Concise move summary with effect description
get_moves_learned_by_pokemon(name_or_id)	All moves a Pokémon can learn, grouped by learn method (level-up, TM/HM, egg, tutor)
list_moves(limit, offset)	Paginated list of all moves (max 100 per page)
get_moves_by_type(type_name)	All moves that belong to a specific type

🎒 Items

Tool	Description
get_item(name_or_id)	Full item details: category, cost, effect, attributes, and held-by Pokémon
get_item_summary(name_or_id)	Concise item summary with short effect and Pokédex flavor text
list_items(limit, offset)	Paginated list of all items (max 100 per page)
get_items_by_category(category)	All items in a category (e.g. pokeballs, healing, held-items, berries, evolution)
get_item_held_by_pokemon(item_name)	All Pokémon that hold an item in the wild, with per-version rarity

🔥 Types

Tool	Description
get_type(name_or_id)	Full type details including damage relations, resident Pokémon, and moves
get_type_matchups(attacking_type)	Offensive chart: super effective / not very effective / no effect / normal
get_type_defenses(defending_type)	Defensive chart: weak to / resists / immune to
get_dual_type_matchups(type_one, type_two)	Combined defensive multipliers for a dual-type Pokémon (4×, 2×, 1×, 0.5×, 0.25×, 0×)
list_types()	List all 18 Pokémon types

---

Resources

Resources are accessible via URI and return raw JSON.

URI pattern	Description
pokedex://pokemon/{name_or_id}	Full Pokémon data
pokedex://species/{name_or_id}	Species data including Pokédex entries
pokedex://move/{name_or_id}	Full move data
pokedex://item/{name_or_id}	Full item data
pokedex://type/{name_or_id}	Full type data with damage relations
pokedex://ability/{name_or_id}	Ability data with effect descriptions
pokedex://generation/{name_or_id}	Generation data with Pokémon species and version groups
pokedex://pokedex/{name_or_id}	Regional Pokédex entries (e.g. national, kanto)

---

Project structure

src/pokemcp/
├── app.py          # Shared FastMCP instance
├── server.py       # Entry point — imports all tools/resources
├── config.py       # Settings via pydantic-settings
├── api/
│   ├── client.py   # Async HTTP client with retry logic
│   └── cache.py    # Redis / in-memory cache layer
├── models/
│   └── pokemon.py  # Pydantic models (Pokemon, PokemonSummary, EvolutionChain)
├── tools/
│   ├── pokemon.py  # Pokémon tools
│   ├── moves.py    # Move tools
│   ├── items.py    # Item tools
│   └── types.py    # Type tools
└── resources/
    └── pokedex.py  # MCP resources

---

Data source

All data is fetched from the PokéAPI — a free, open REST API for Pokémon data. No API key required.