pokemon-mcp-server

Divyanshi88/pokemon-mcp-server

3.1

If you are the rightful owner of pokemon-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Pokémon MCP Server is a Model Context Protocol server that provides AI models with access to comprehensive Pokémon data and battle simulation capabilities.

Tools
1
Resources
0
Prompts
0

Pokémon MCP Server

A Model Context Protocol (MCP) server that provides AI models with access to comprehensive Pokémon data and battle simulation capabilities. This server bridges AI systems with the Pokémon world, enabling them to retrieve detailed information about any Pokémon and simulate battles between them.

📋 Features

Pokémon Data Resource

  • Retrieve detailed information about any Pokémon, including:
    • Base stats (HP, Attack, Defense, Special Attack, Special Defense, Speed)
    • Types (e.g., Fire, Water, Grass)
    • Abilities
    • Available moves and their effects
    • Evolution information

Battle Simulation Tool

  • Simulate battles between any two Pokémon with realistic mechanics:
    • Type effectiveness calculations
    • Damage calculations based on stats and move power
    • Turn order based on Speed stats
    • Support for status effects (Burn, Poison, Paralysis, Sleep)
    • Detailed battle logs showing each action and outcome
    • Winner determination based on which Pokémon faints first

🚀 Getting Started

Prerequisites

  • Python 3.8 or higher
  • pip package manager

Installation

  1. Clone the repository

    git clone https://github.com/yourusername/pokemon-mcp-server.git
cd pokemon-mcp-server

  2. Create a virtual environment (optional but recommended)

    python -m venv venv
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

  3. Install dependencies

    pip install -r requirements.txt

Running the Server

  1. Start the FastAPI server

    cd pokemon/pokemon_mcp
uvicorn main:app --reload

  2. Access the API documentation

    Open your browser and go to http://127.0.0.1:8000/docs to see the interactive API documentation.

📚 API Documentation

Endpoints

GET /
  • Returns a welcome message
  • Response: {"message": "Welcome to the Pokémon MCP Server! Use /query or /battle endpoints."}
GET /query
  • Retrieves information about a specific Pokémon
  • Query Parameters:
    • name: Name of the Pokémon (case-insensitive)
  • Example: GET /query?name=pikachu
  • Response: A PokemonInfo object containing all available data about the Pokémon
GET /battle
  • Simulates a battle between two Pokémon
  • Query Parameters:
    • pokemon1: Name of the first Pokémon
    • pokemon2: Name of the second Pokémon
  • Example: GET /battle?pokemon1=charizard&pokemon2=blastoise
  • Response: A BattleResult object containing the winner, number of rounds, moves used, and detailed battle log

🧬 Project Structure

pokemon-mcp-server/
├── pokemon/
│   └── pokemon_mcp/
│       ├── models/
│       │   └── pokemon_models.py     # Data models for the API
│       ├── services/
│       │   └── pokedex.py            # Service to fetch Pokémon data
│       ├── tools/
│       │   └── battle_simulator.py   # Battle simulation logic
│       └── main.py                   # FastAPI application
└── requirements.txt                  # Project dependencies

🔧 Core Components

PokéAPI Integration

The server connects to the public PokéAPI to fetch comprehensive Pokémon data. This data is then processed and structured for easy consumption by AI models.

Battle System

The battle simulation system includes:

  • Type Effectiveness: Implements the Pokémon type chart where certain types are super effective, not very effective, or have no effect against other types
  • Damage Calculation: Uses realistic formulas based on the Pokémon games
  • Status Effects:
    • Burn: Reduces attack and causes damage each turn
    • Poison: Causes increasing damage each turn
    • Paralysis: Reduces speed and may cause the Pokémon to skip turns
    • Sleep: Causes the Pokémon to skip turns for a random number of turns

💡 Examples for LLMs

How an LLM would query the resource:

  1. To get information about a Pokémon:

    GET http://localhost:8000/query?name=eevee

  2. To simulate a battle between two Pokémon:

    GET http://localhost:8000/battle?pokemon1=pikachu&pokemon2=sandshrew

Example Response Analysis:

The LLM can analyze battle results to explain:

  • Why certain moves were super effective
  • How status effects impacted the battle
  • Which Pokémon's stats gave it an advantage
  • How evolution stage affected battle outcomes

🔌 MCP Compliance

This server follows the Model Context Protocol design patterns for resources and tools, enabling:

  • Structured Data Access: LLMs can easily navigate and understand the structured Pokémon data
  • Tool Integration: LLMs can invoke the battle simulation tool with parameters and interpret the results
  • Context-Aware Interactions: LLMs can maintain context about Pokémon types, moves, and battle mechanics

🛣️ Future Enhancements

  • Add more sophisticated battle mechanics (weather effects, abilities, held items)
  • Implement team battles (2v2, 3v3)
  • Create a battle replay visualization
  • Expand to include more Pokémon game mechanics (breeding, training, etc.)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments