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

Clone and install dependencies:

git clone <repository>
cd pokedex
pnpm install

Build the project:
```
pnpm build
```
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

Follow existing code patterns and architecture
Maintain TypeScript strict mode compliance
Add appropriate error handling for new features
Update formatters for consistent response formatting
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.

Pokédex MCP Server

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

Clone and install dependencies:

git clone <repository>
cd pokedex
pnpm install

Build the project:
```
pnpm build
```
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

Follow existing code patterns and architecture
Maintain TypeScript strict mode compliance
Add appropriate error handling for new features
Update formatters for consistent response formatting
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.