Pokemon MCP Project 🎮

A Model Context Protocol (MCP) server that provides Pokemon data and battle simulation capabilities to AI assistants like Claude Desktop.

Features ✨

• Pokemon Data Resource: Access comprehensive Pokemon information including stats, types, abilities, and moves
• Battle Simulation Tool: Simulate battles between any two Pokemon with type effectiveness and status effects
• Type Effectiveness System: Accurate damage calculations based on Pokemon type matchups
• Status Effects: Burn, Poison, and Paralysis effects implemented
• Data Caching: Efficient caching system to minimize API calls

Project Structure 📁

Poke-MCP/
├── src/
│   ├── server.py            # Main MCP server with the tool and the resource
│   ├── pokemon_types.py     # Data classes for Pokemon, Moves, etc.
│   ├── datastore.py         # Pokemon data fetching and caching
│   ├── battle.py            # Battle simulation logic
│   ├── mechanics.py         # Battle mechanics (damage, STAB, etc.)
│   ├── type_chart.py        # Type effectiveness chart
│   └── utils.py             # Utility functions and logging
├── data/                    # Cache storage (created automatically)
├── .venv/                   # Virtual environment
├── pyproject.toml           # Project configuration and dependencies
└── README.md                # This file

Prerequisites 📋

• Python 3.10 or higher
• pip (Python package manager)
• Internet connection (for fetching Pokemon data from PokeAPI)

Installation 🚀

Step 1: Clone/Download the Project

# If you have the zip file, extract it first
# Then navigate to the project directory
cd Poke-MCP

Step 2: Create Virtual Environment (Recommended)

# Windows
python -m venv .venv
.venv\Scripts\activate

# Mac/Linux
python -m venv .venv
source .venv/bin/activate

Step 3: Install Dependencies

# Using pyproject.toml (recommended)
pip install -e .

# Or using pip directly
pip install mcp[cli]>=1.2.0 httpx>=0.26.0

Running the Server 🎯

Basic Server Start

# Make sure virtual environment is activated
python -m src.server

Note: The server will run silently (no output) when working correctly. This is intentional - it's waiting for MCP client connections via STDIO.

Verify Server is Running

• The terminal will appear to "hang" - this means it's working!
• Press Ctrl+C to stop the server
• Check that data/ and src/__pycache__/ folders are created

Using with Claude Desktop 🤖

Step 1: Locate Claude Desktop Config

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Step 2: Add Server Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "pokemon": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "C:/full/path/to/your/Poke-MCP"
    }
  }
}

--------------
If the above didn't work use the following:
--------------
{
  "mcpServers": {
    "pokemon": {
      "command": "cmd",
      "args": ["/c", "cd /d C:/full/path/to/your/Poke-MCP && .venv\\Scripts\\python.exe -m src.server"]
    }
  }
}

Important: Replace C:/full/path/to/your/Poke-MCP with your actual project path including the Poke-MCP in the end of the path!

Step 3: Restart Claude Desktop

If Claude Desktop is already running close it and reopen it to load the new configuration.

Step 4: Activate Tools and Include Resources if not

Usually if Claude Desktop detectes the server it activates the tools automatically, but the resources need to be included in the chat messages (new chat -> press the + button -> click on Add from pokemon -> click on pokemon_list) and then it will be added to this only specific message.

Step 5: Test in Claude

Ask Claude:

• "Can you list available Pokemon?"
• "Show me details about Pikachu"
• "Simulate a battle between Charizard and Blastoise"

Available MCP Resources 📚

List Pokemon

• Parameters: No parameters needed. Also either way Claude Desktop dosen't accept parameters in the resources.
• Returns: List of 20 Pokemons with mostly all of the information of each one of them!

Available MCP Tools 🛠️

Battle Simulation

• Parameters:

  • pokemonA_name: Name or ID of first Pokemon
  • pokemonB_name: Name or ID of second Pokemon
  • pokemonA_level: Level of first Pokemon (1-100, default: 50)
  • pokemonB_level: Level of second Pokemon (1-100, default: 50)
  • pokemonA_moves: Optional list of moves for first Pokemon
  • pokemonB_moves: Optional list of moves for second Pokemon
  • seed: Optional seed for reproducible battles
  • max_turns: Maximum battle turns (default: 200)

• Returns: JSON string with these fields:

  winner — the winning Pokémon’s name (or a draw indicator)

  turns — how many turns the battle took

  log — an ordered list of turn-by-turn messages

  summary — a short human-readable wrap-up

Troubleshooting 🔧

Server appears to hang with no output

This is normal! The server runs silently when using STDIO transport. It's waiting for client connections.

ImportError: No module named 'mcp'

Install dependencies:

pip install mcp[cli]>=1.2.0

Port already in use (when using inspector)

# Find and kill the process
netstat -ano | findstr :6277
taskkill /PID [PID_NUMBER] /F

KeyboardInterrupt traceback when stopping server

This is normal! It's Python's way of confirming the server stopped when you pressed Ctrl+C.

Implementation Details 🔍

Battle Mechanics

• Damage Formula: Uses simplified version of the official Pokemon damage formula.
• Type Effectiveness: Fire > Grass, Water > Fire, etc.
• STAB Bonus: 1.5x damage for moves matching Pokemon type.
• Critical Hits: 6.25% chance for 1.5x damage.
• Speed: Determines turn order.
• Status Effects:
  • Burn: 1/16 HP loss per turn, halves physical damage
  • Poison: 1/8 HP loss per turn
  • Paralysis: 25% speed reduction, 25% chance to skip turn

Data Source

• Pokemon data fetched from PokeAPI
• Cached locally in data/cache.json to reduce API calls

Project Requirements Met ✅

• ✅ MCP server implementation using FastMCP
• ✅ Pokemon data resource with comprehensive information
• ✅ Battle simulation tool with game mechanics
• ✅ Type effectiveness calculations
• ✅ Status effects (Burn, Poison, Paralysis)
• ✅ Turn order based on Speed stats
• ✅ Detailed battle logs
• ✅ Evolution information
• ✅ Move and ability data

---

If you encounter any issues:

• Check the Troubleshooting section above
• Ensure all dependencies are installed
• Verify Python version is 3.10+
• Check that the virtual environment is activated

---

Thank you.