RuDi07R/Pokemon-MCP_server
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
🚀 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" ]
}