Pokédex MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Pokémon data access through the PokeAPI. This server enables AI agents to fetch detailed Pokémon information, type effectiveness charts, encounter locations, and search capabilities.

Features

• Detailed Pokémon Information: Get comprehensive data including stats, abilities, types, sprites, and artwork
• Type Effectiveness: Complete damage relationship charts for all Pokémon types
• Encounter Locations: Wild encounter data with locations, levels, and capture methods
• Search Functionality: Find Pokémon by partial name matching
• REST API Client: Full TypeScript client for PokeAPI v2 with type safety
• Zod Validation: Runtime schema validation for all tool inputs
• Clean Architecture: Modular design with separated concerns

Architecture

The server is built with a clean, modular architecture:

src/
├── index.ts       # MCP server entry point and transport setup
├── tools.ts       # MCP tool definitions and registration
├── client.ts      # PokeAPI REST client with TypeScript types
├── formatters.ts  # Response formatting utilities
└── fetcher.ts     # GraphQL client (legacy, replaced by REST client)

Core Components

• MCP Server: Uses @modelcontextprotocol/sdk for protocol compliance
• REST API Client: Comprehensive PokeAPI v2 client with full TypeScript support
• Zod Validation: Runtime type checking and schema validation
• Response Formatters: Centralized formatting for consistent output

Available Tools

fetch_pokemon

Fetch detailed information about a Pokémon by name or ID.

Parameters:

• name (string): The name or ID of the Pokémon

Example Response:

**pikachu** (ID: 25)
Height: 4 decimetres (0.4m)
Weight: 60 hectograms (6.0kg)
Base Experience: 112
Order: 35

**Types:** electric
**Abilities:** static, lightning-rod (hidden)
**Base Stats:** hp: 35, attack: 55, defense: 40, special-attack: 50, special-defense: 50, speed: 90

**Sprites:**
- Default: https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/25.png
- Shiny: https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/shiny/25.png
- Artwork: https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/25.png

get_type_effectiveness

Get type effectiveness information including strengths, weaknesses, and resistances.

Parameters:

• name (string): The name or ID of the type

Example Response:

**FIRE Type Effectiveness**

**Strong Against (2x damage to):** grass, ice, bug, steel
**Weak Against (0.5x damage to):** fire, water, rock, dragon
**No Effect Against (0x damage to):** None

**Resistant To (0.5x damage from):** fire, grass, ice, bug, steel, fairy
**Vulnerable To (2x damage from):** water, ground, rock

**Pokémon with this type:** charmander, charmeleon, charizard, vulpix, ninetales, growlithe and 58 more...

get_pokemon_encounters

Get location encounter information for a Pokémon.

Parameters:

• name (string): The name or ID of the Pokémon

Example Response:

**pikachu Encounter Locations:**

**viridian forest:**
  red: walk (Lv.3-5, 5% chance)
  blue: walk (Lv.3-5, 5% chance)
  yellow: walk (Lv.4-6, 100% chance)

**power plant:**
  red: walk (Lv.20-24, 25% chance)
  blue: walk (Lv.20-24, 25% chance)

search_pokemon

Search for Pokémon by partial name match.

Parameters:

• query (string): Partial name to search for

Example Response:

**Search results for "char":**

1. charmander (ID: 4)
2. charmeleon (ID: 5)
3. charizard (ID: 6)

*Use fetch_pokemon with any of these names to get detailed information.*

Installation

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm

Setup

1. Clone and install dependencies:

   git clone <repository>
   cd pokedex
   pnpm install
   

2. Build the project:

   pnpm build
   

3. Run the server:

   node dist/index.js
   

Development

Project Structure

pokedex/
├── src/
│   ├── index.ts       # Server entry point
│   ├── tools.ts       # MCP tool definitions  
│   ├── client.ts      # PokeAPI REST client
│   ├── formatters.ts  # Response formatting
│   └── fetcher.ts     # GraphQL client (legacy)
├── dist/              # Compiled JavaScript
├── package.json       # Dependencies and scripts
├── tsconfig.json      # TypeScript configuration
├── CLAUDE.md          # Development guidelines
└── README.md          # This file

Available Scripts

# Build TypeScript to JavaScript
pnpm build

# Run tests
pnpm test

# Build and run server
pnpm build && node dist/index.js

Development Guidelines

• ES Modules: Project uses "type": "module" for modern JavaScript
• TypeScript: Strict mode enabled with ES2022 target
• Code Style: Formatted with consistent patterns
• Validation: All inputs validated with Zod schemas
• Error Handling: Comprehensive error catching and user-friendly messages

MCP Integration

Claude Desktop Integration

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "pokedex": {
      "command": "node",
      "args": ["/path/to/pokedex/dist/index.js"],
      "env": {}
    }
  }
}

Other MCP Clients

The server implements the standard MCP protocol and works with any compliant client:

• Transport: stdio (standard input/output)
• Protocol Version: 2025-06-18
• Capabilities: tools (with listChanged support)

API Coverage

This server provides access to major PokeAPI v2 endpoints:

• Pokémon Data: /pokemon/{id or name} - Complete Pokémon information
• Type Information: /type/{id or name} - Type effectiveness and relationships
• Encounter Data: /pokemon/{id}/encounters - Wild encounter locations
• Search: /pokemon list endpoint for name-based searching

Dependencies

Runtime Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• zod: Runtime type validation and schema definition

Development Dependencies

• typescript: TypeScript compiler and language support
• @types/node: Node.js type definitions

Contributing

1. Follow existing code patterns and architecture
2. Maintain TypeScript strict mode compliance
3. Add appropriate error handling for new features
4. Update formatters for consistent response formatting
5. Test with MCP clients before submitting changes

API References

• PokeAPI: https://pokeapi.co/docs/v2
• MCP Protocol: https://modelcontextprotocol.io
• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

License

This project provides educational access to Pokémon data through the public PokeAPI service. All Pokémon data is owned by The Pokémon Company.