Athlon07/Pokemon-mcp-server

Pokémon MCP Battle ServerThis project provides a Pokémon battle simulator powered by the PokéAPI and the Model Context Protocol (MCP). It exposes MCP tools so that an LLM (or MCP inspector) can fetch Pokémon, fetch moves, start battles, and play turn-based battles with proper damage mechanics, type effectiveness, and status effects.

✨ Features

• Fetch Pokémon: Fetches data from PokéAPI with caching to avoid repeated API calls.
• Fetch Moves: Retrieves move metadata like power, type, and status effects, also with caching.
• Turn-Based Battle System: Includes a comprehensive battle system with:Damage calculation (STAB, type effectiveness, critical hits).
• Status conditions (paralysis, sleep, burn, poison, freeze).End-of-turn effects (poison/burn damage, sleep duration).
• Random Opponent: The opponent is chosen randomly from the full Pokédex for varied gameplay.

Flow Chart depicitng functionalities

flowchart TD
    A[PokéAPI] --> B["MCP Client: Claude Desktop"]
    B --> C["MCP Server: Pokémon Battle Engine"]
    C --> D[MCP Tools]

    subgraph Tools [Available MCP Tools]
        D1[get_pokemon]
        D2[get_move]
        D3[start_battle]
        D4[play_turn]
        D5[play_turn_chance]
    end

    D --> D1
    D --> D2
    D --> D3
    D --> D4
    D --> D5

📦 InstallationClone or download this repository:

git clone [https://github.com/Athlon07/Pokemon-mcp-server.git]
cd Pokemon-mcp-server

Make sure you have Python 3.10+ installed. Create a virtual environment and install the dependencies:

Create and activate the virtual environment

python -m venv venv
venv\Scripts\activate

Install required packages

pip install -r requirements.txt
The requirements.txt file contains:
requests
mcp[fastmcp]
mcp[cli]

🚀 Running the ServerStart the MCP server with the following command in your terminal:

python server.py

Connecting to an MCP Client (e.g., Claude Desktop):

Edit your client's configuration file to point to your local server. You will need to provide the absolute path to the server.py file.

{
  "mcpServers": {
    "pokemon-mcp": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "cwd": "/path/to/your/project/directory"
    }
  }
}

🛠️ Available MCP Tools

• get_pokemon(name: str)Fetches Pokémon details, including stats, types, and available moves. Example: "pikachu" → { "stats": {...}, "types": ["electric"], ... }
• get_move(name: str)Fetches move metadata, such as power, accuracy, type, and any ailment effects. Example: "thunderbolt"
• start_battle(user_pokemon: str) Starts a battle between your chosen Pokémon and a randomly selected opponent. Returns the complete initial battle state, including HP, turn number, and a battle log.
• play_turn(state: dict, move_user: str) Plays one turn of the battle. You provide the current battle state and your chosen move. The opponent will select and execute its move automatically.
• play_turn_chance(state: dict, move_user: str) This is an alias for play_turn for compatibility purposes. It functions identically.

📝 Notes

• Uses PokéAPI as the data source
• Caches requests for efficiency
• Server can be connected to any MCP-compatible client
• Extendable with new mechanics or custom battle rules

🌟 Benefits

• Interactive Pokémon battle system
• Lightweight and serverless MCP protocol integration
• Expandable battle logic (more conditions, moves, or AI strategies)
• Perfect playground for LLM + Pokémon mechanics experiments