Pokémon MCP Server — Data Resource + Battle Simulation Tool
Overview
This project implements an MCP (Model Context Protocol) server that provides AI models with access to two key capabilities:
1- Pokémon Data Resource – a resource that exposes comprehensive Pokémon data from the public PokéAPI ( https://pokeapi.co/ ).
2- Battle Simulation Tool – a tool that simulates battles between any two Pokémon, including type effectiveness, stats-based damage, turn order, and basic status effects.
This server acts as a bridge between AI and the Pokémon world, enabling LLMs to both retrieve knowledge and interactively simulate battles.
Part 1: Pokémon Data Resource
Implementation
-
Connects to the public PokéAPI ( https://pokeapi.co/ )
-
Exposes comprehensive Pokémon information including:
-
Base stats: HP, Attack, Defense, Special Attack, Special Defense, Speed
-
Types (e.g., Fire, Water, Grass)
-
Abilities
-
Available moves and their effects (power, accuracy, type, effect text)
-
Evolution information
MCP Resource
- Resource: pokemon://{name}
- Returns JSON including stats, types, abilities, moves (with effects), and evolution chain.
- Implements MCP resource design patterns to make this data accessible to LLMs.
Deliverables
- Code for the MCP server with the Pokémon data resource.
- Documentation (this README) describing how the resource exposes data.
- Example queries (examples/llm_examples.md).
Part 2: Battle Simulation Tool
Implementation
-
Tool: simulate_battle(pokemon_a, pokemon_b, max_turns=100, seed=None)
-
Simulates a battle between any two Pokémon using:
-
Type effectiveness calculations (e.g., Water > Fire)
-
Damage calculations based on stats and move power
-
Turn order based on Speed stat
Status effects:
- Paralysis – chance to skip a turn
- Burn – recurring HP loss
- Poison – recurring HP loss
- Detailed battle logs showing each turn’s actions and outcomes
- Winner determination (first Pokémon to faint, or higher HP after max turns)
MCP Tool
- Exposed via MCP as a callable tool: simulate_battle
- Returns JSON object, e.g.:
{
"winner": "blastoise",
"log": [
"--- Turn 1 ---",
"charizard used fire-punch → blastoise lost 14 HP!",
"blastoise is now affected by burn!",
...
]
}
Deliverables
- Code for the battle simulation tool following MCP tool specification
- Example usage in examples/llm_examples.md
Project Packaging
The submission includes a ZIP file containing:
- All code (pkmon_core/server.py, pkmon_core/battle.py)
- Supporting files (requirements.txt, README.md, examples/)
- A test script (test_part1.py)
- Clear instructions for setup and usage
Installation & Setup
Requirements
- Python 3.10+
- Virtual environment recommended
Setup
git clone https://github.com/TaifAlsadoon/pokemon-mcp-server.git
cd pokemon-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Running & Testing
Run the MCP Server
python -m pkmon_core.server
Note: The server runs in stdio mode and will appear idle, waiting for an MCP client. Stop with Ctrl+C.
Quick Python Tests
python - << 'PY'
from pkmon_core.server import get_pokemon, simulate_battle
print("Resource sample (pikachu) ->")
print(get_pokemon("pikachu")[:200], "...\n")
print("Battle sample ->")
res = simulate_battle("charizard", "blastoise", seed=42, max_turns=20)
print("Winner:", res["winner"])
print("\n".join(res["log"][:10]))
PY
Expected output:
- JSON data for Pikachu (types, stats, moves, evolution chain)
- Battle log with turn-by-turn actions and a winner (e.g., Blastoise)
Examples for LLM Usage
See examples/llm_examples.md for prompt examples, such as:
- Summarizing a Pokémon’s stats, moves, and evolution
- Simulating a battle and explaining why the winner won
See examples/llm_examples.md for prompt examples.
Notes
- Simplified mechanics: ignores PP, items, weather, etc.
- Focused on clarity and educational battle simulation
- Easily extensible to add more mechanics