Pokemon MCP Servers

A collection of Model Context Protocol (MCP) servers for accessing Pokemon data through AI assistants like Claude Desktop, Cursor, and other MCP clients.

Quick Start

Prerequisites

• Python 3.12+ with uv package manager
• Docker Desktop (for Evolutions Server / Neo4j)
• Node.js (for MCP Inspector testing)

Setup

# Clone repository
git clone https://github.com/frabatx/pokemon-mcp-servers.git
cd pokemon-mcp-servers

# Setup a server (e.g. Biography Server)
cd servers/biography-server
uv sync
uv run main.py
# Expected: [READY] Server listening on stdio

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run main.py
# Open http://localhost:5173

Neo4j Setup (Evolutions Server)

# From project root
./setup.sh          # macOS/Linux
.\setup.ps1         # Windows PowerShell

Available Servers

Server	Description	Data Source	Tools
Biography Server	Detailed Pokemon biographies	biographies.json (809 Pokemon)	4 tools
Statistics Server	Combat stats, type analysis, comparisons	statistics.csv (41 columns)	16 tools
Evolutions Server	Evolution chains and type relationships	Neo4j graph database	2 tools

Project Architecture

pokemon-mcp-servers/
├── data/                           # Shared data
│   ├── biographies.json
│   ├── statistics.csv
│   └── pokemon.cypher
├── docs/                           # Documentation
│   ├── registry-pattern.md         # Design pattern deep dive
│   └── new-server-guide.md         # How to create a new server
├── servers/                        # Independent MCP servers
│   ├── biography-server/
│   ├── statistics-server/
│   └── evolutions-server/
├── docker-compose.yml              # Neo4j infrastructure
└── setup.sh / setup.ps1            # One-command Neo4j setup

Each server follows the same structure:

my-server/
├── main.py              # Entry point (uv run main.py)
├── src/
│   ├── tools/
│   │   ├── __init__.py  # Auto-registration
│   │   ├── register.py  # Registry pattern
│   │   └── *.py         # Tool implementations
│   └── utils/
│       └── load_data.py # Data loading
└── pyproject.toml

Registry Pattern

This project uses an advanced Registry Pattern for scalable tool management. Adding a new tool = creating 1 file. No changes needed in main.py.

See docs/registry-pattern.md for the full deep dive.

Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pokemon-biography": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/absolute/path/to/pokemon-mcp-servers/servers/biography-server"
    },
    "pokemon-statistics": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/absolute/path/to/pokemon-mcp-servers/servers/statistics-server"
    },
    "pokemon-evolutions": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/absolute/path/to/pokemon-mcp-servers/servers/evolutions-server",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "pokemon-biography": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/absolute/path/to/pokemon-mcp-servers/servers/biography-server"
    }
  }
}

Resources

Resources provide static data that AI assistants can read for context without calling a tool.

Biography Server

URI	Description
pokemon://biography/list	Complete list of all 809 Pokemon names
pokemon://biography/{name}	Biography of a specific Pokemon (template)

Statistics Server

URI	Description
pokemon://stats/types	All 18 Pokemon types
pokemon://stats/generations	Generations with Pokedex ranges and counts
pokemon://stats/type-chart	Type effectiveness chart (weaknesses, resistances, immunities)
pokemon://stats/schema	Dataset schema with all column definitions

Prompts

Prompts are pre-configured workflows that guide the AI through multi-step tasks.

Biography Server

Prompt	Description
pokemon-quiz	Interactive quiz: guess the Pokemon from biography excerpt
pokemon-comparison	Detailed comparison between two Pokemon
evolution-story	Narrative story about a Pokemon's evolution journey

Statistics Server

Prompt	Description
build-team	Build a competitive team of 6 with balanced type coverage
type-matchup-analysis	Analyze type matchups and coverage gaps for a team
counter-finder	Find best counters for opponent Pokemon

Tools Reference

Biography Server (4 tools)

Tool	Description
search_biography	Search Pokemon biography by name
search_biography_fulltext	Full-text search across all biographies
get_random_biography	Get a random Pokemon biography
list_all_pokemon	List all available Pokemon

Statistics Server (16 tools)

Tool	Description
get_pokemon_stats	Get complete stats for a Pokemon
calculate_type_effectiveness	Calculate type effectiveness multipliers
get_resistances_and_weaknesses	Get a Pokemon's type resistances/weaknesses
find_pokemon_resistant_to_types	Find Pokemon resistant to given types
filter_pokemon_multi_criteria	Filter Pokemon by multiple criteria
get_pokemon_by_stat_range	Find Pokemon within a stat range
get_pokemon_by_type_combination	Find Pokemon by type1/type2 combo
get_pokemon_by_ability	Find Pokemon by ability
get_pokemon_by_generation	List Pokemon by generation
compare_pokemon_head_to_head	Compare two Pokemon stats
find_similar_pokemon	Find statistically similar Pokemon
get_top_pokemon_by_stat	Top N Pokemon by a specific stat
get_extreme_pokemon	Pokemon with highest/lowest stats
calculate_stat_percentile	Calculate stat percentile ranking
aggregate_stats_by_type	Aggregate statistics by type
calculate_bst_distribution	Base Stat Total distribution analysis

Evolutions Server (2 tools)

Tool	Description
get_pokemon_types	Get type information from graph
get_pokemon_evolutions	Get evolution chain from graph

Creating a New Server

See docs/new-server-guide.md for the step-by-step guide.

Data Schema

biographies.json

{"name": "Pikachu", "bio": "Biology [ edit ] Pikachu is..."}

statistics.csv (41 columns)

Main columns: name, pokedex_number, hp, attack, defense, sp_attack, sp_defense, speed, base_total, type1, type2, abilities, against_* (18 type effectiveness columns), height_m, weight_kg, generation, is_legendary

Troubleshooting

Problem	Solution
Tool not registered	Check import in src/tools/__init__.py
get_all_tools() returns empty	Import tools AFTER importing register.py
Module not found	Run uv sync
Inspector can't connect	All prints must be to stderr, not stdout
Import errors	Verify src/ has __init__.py files

Resources

• MCP Documentation
• Python MCP SDK
• MCP Inspector

License

MIT License - see LICENSE for details.

Author

Francesco Battista - @frabatx