Pokemon-MCP_server

RuDi07R/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.

This project is a full-featured Pokémon battle simulator and data server using a Model Context Protocol (MCP) compliant FastAPI backend.

Pokémon Battle Simulator & MCP Server

This project is a full-featured Pokémon battle simulator and data server. It uses a Model Context Protocol (MCP) compliant FastAPI backend to provide comprehensive Pokémon data and a powerful battle engine. The user interface is an interactive, multi-page web application built with Streamlit.


⭐ Features

  • Interactive Battle Simulator: A full-featured UI to select Pokémon and watch turn-by-turn battles unfold with visual feedback.
  • Multiple Battle Modes: Supports 1v1, Random, and strategic 3v3 Team battles.
  • Advanced Battle Engine: Implements core Pokémon mechanics, including:
    • Type Effectiveness & Damage Calculation
    • Turn Order based on Speed stats
    • 5+ Status Effects (Poison, Burn, Paralysis, Sleep, Confusion)
    • AI Move Selection (chooses super-effective or high-power moves)
  • Full-Featured Pokédex: A searchable page to view detailed data, stats, and official artwork for over 898 Pokémon.
  • Strategic Move Recommender: A tool that analyzes a matchup and recommends the best move for an attacker to use.
  • Custom Pokémon Support: Includes three custom-defined Pokémon (Scopely, EA Sports, and Zynga) with unique stats, abilities, and local image support.
  • High-Performance Caching: Integrated with Redis to cache API calls, ensuring a fast and smooth user experience.

🛠️ Tech Stack

Python FastAPI Streamlit Redis


🚀 Local Setup and Run Instructions

This project is designed to be run locally.

1. Prerequisites
  • Python 3.9+
  • A running Redis server.
2. Installation

In your terminal, navigate to the project's root folder and run the following commands:

# Create and activate a Python virtual environment
python -m venv venv

# On Windows:
# .\venv\Scripts\activate
# On macOS/Linux:
# source venv/bin/activate

# Install all required dependencies
pip install -r requirements.txt
3. Running the Application

You will need two separate terminals running in the project's root folder.

Terminal 1: Start the Backend MCP Server

# Make sure your virtual environment is active
uvicorn app.main:app --reload

The API server will be available at http://127.0.0.1:8000. Interactive documentation can be found at http://127.0.0.1:8000/docs.

Terminal 2: Start the Frontend Streamlit App

# Make sure your virtual environment is active
streamlit run Battle_Simulator.py

The application will open in your web browser.


💡 Future Development

  • Full Containerization: Containerize the application using docker-compose to streamline deployment and enhance scalability.
  • Team Analyst Tool: A new page that analyzes a team of six Pokémon and provides a strategic report on its overall type strengths and weaknesses.
  • Persistent Battle History: Save battle log results to a simple database (like SQLite) to create a persistent history of past matches.

⚙️ MCP API Usage Example

The server can be queried directly using any API client. Here is an example of fetching data for Snorlax.

Example Query
curl -X POST -H "Content-Type: application/json" \
-d '{"resource": "pokemon_data", "action": "get", "params": {"name": "snorlax"}}' \
[http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp)
Example Response
{
  "id": 143,
  "name": "Snorlax",
  "stats": { "hp": 160, "attack": 110, "defense": 65, "special-attack": 65, "special-defense": 110, "speed": 30 },
  "types": [ "normal" ],
  "abilities": [ "immunity", "thick-fat", "gluttony" ],
  "moves": [ { "name": "mega-punch", "power": 80, "type": "normal" } ],
  "evolution_chain": [ "munchlax", "snorlax" ]
}