pokemon_mcp_server

krishna663-wq/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 dayong@mcphub.com.

The Pokémon Battle Simulation MCP Server provides AI models with access to comprehensive Pokémon data and battle simulation capabilities using the Model Context Protocol.

Tools
2
Resources
0
Prompts
0

Pokémon Battle Simulation MCP Server

A Model Context Protocol (MCP) server that provides AI models with access to Pokémon data and battle simulation capabilities.

Features

1. Pokémon Data Resource

  • Comprehensive Pokémon information from PokéAPI
  • Base stats (HP, Attack, Defense, Special Attack, Special Defense, Speed)
  • Types, abilities, and moves
  • Evolution information and sprite URLs
  • Intelligent caching for improved performance

2. Battle Simulation Tool

  • Full battle mechanics implementation
  • Type effectiveness calculations
  • Damage calculations based on stats and moves
  • Turn order determination by Speed stats
  • Status effects: Burn, Poison, Paralysis, Sleep
  • Detailed battle logs with turn-by-turn breakdown
  • Winner determination

Installation

  1. Clone or download the project files

  2. Install dependencies:

    pip install -r requirements.txt

  3. Run the server:

    python pkmon_core/server.py

    Or as a module:

    python -m pkmon_core.server

Usage

Starting the Server

Run the MCP server:

python pkmon_core/server.py

The server communicates via stdin/stdout following the MCP protocol.

Available Resources

Pokemon Data Resource
  • URI: pokemon://data/search
  • Description: Access comprehensive Pokémon data
  • Usage: Query using the get_pokemon_data tool

Available Tools

1. get_pokemon_data

Get detailed information about any Pokémon.

Parameters:

  • name (string): Pokémon name or Pokédex ID

Example:

{
  "name": "get_pokemon_data",
  "arguments": {
    "name": "pikachu"
  }
}

Response includes:

  • ID and name
  • Types (e.g., ["electric"])
  • Base stats (HP, Attack, Defense, etc.)
  • Abilities
  • Available moves with power, accuracy, and effects
  • Physical characteristics (height, weight)
  • Sprite URL
2. simulate_battle

Simulate a battle between two Pokémon with realistic mechanics.

Parameters:

  • pokemon1 (string): First Pokémon name or ID
  • pokemon2 (string): Second Pokémon name or ID

Example:

{
  "name": "simulate_battle",
  "arguments": {
    "pokemon1": "pikachu",
    "pokemon2": "charizard"
  }
}

Response includes:

  • Final HP for both Pokémon
  • Winner determination
  • Complete battle log with:
    • Move usage and damage
    • Type effectiveness messages
    • Status effect applications
    • Turn-by-turn progression

Battle Mechanics

Damage Calculation

  • Based on official Pokémon formulas
  • Considers attack/defense stats and move power
  • Includes type effectiveness multipliers
  • STAB (Same Type Attack Bonus) applied
  • Random damage variation (85-100%)

Type Effectiveness

  • Complete type chart implementation
  • Super effective (2x damage)
  • Not very effective (0.5x damage)
  • No effect (0x damage)

Status Effects

  1. Burn: Reduces physical move damage by 50%, deals HP/16 damage per turn
  2. Poison: Deals HP/8 damage per turn
  3. Paralysis: 25% chance to be unable to move each turn
  4. Sleep: Pokémon cannot move for 1-3 turns

Turn Order

  • Determined by Speed stats
  • Faster Pokémon moves first
  • Status effects processed at start of each turn

Example Usage

Getting Pokémon Data

# Example LLM query to the server
"Get me information about Charizard"

The server will return comprehensive data including:

  • Base stats: HP 78, Attack 84, Defense 78, etc.
  • Types: Fire/Flying
  • Abilities: Blaze, Solar Power
  • Notable moves: Flamethrower, Dragon Pulse, etc.

Battle Simulation

# Example LLM query
"Simulate a battle between Pikachu and Squirtle"

Sample battle output:

Battle begins! pikachu vs squirtle!
pikachu: 35 HP
squirtle: 44 HP
---
Turn 1
pikachu uses thunder-shock! Deals 12 damage to squirtle.
squirtle: 32/44 HP
squirtle uses water-gun! Deals 8 damage to pikachu.
pikachu: 27/35 HP
---
Turn 2
pikachu uses quick-attack! Deals 6 damage to squirtle.
squirtle: 26/44 HP
...
Winner: pikachu!

API Integration

The server uses the PokéAPI to fetch real-time Pokémon data:

  • Automatic caching to reduce API calls
  • Comprehensive move data including effects
  • Official stats and type information
  • High-quality sprite images

Architecture

Core Components

  1. PokemonMCPServer: Main server class handling MCP protocol
  2. Pokemon Data Models: Type-safe data structures using dataclasses
  3. Battle Engine: Implements game mechanics and calculations
  4. API Client: Async HTTP client for PokéAPI integration

Data Flow

  1. LLM requests Pokémon data or battle simulation
  2. Server validates request and parameters
  3. Fetches required data from PokéAPI (with caching)
  4. Processes battle mechanics if simulating
  5. Returns structured JSON response

Configuration

Environment Variables

No environment variables required - the server works out of the box.

Customization Options

  • Modify type_effectiveness dictionary for custom type charts
  • Adjust status effect durations in apply_status_effect()
  • Change battle turn limit (default: 50 turns)
  • Customize move selection logic in simulate_battle()

Troubleshooting

Common Issues

  1. "Could not find Pokemon" error

    • Ensure correct spelling of Pokémon name
    • Try using Pokédex ID number instead
    • Check PokéAPI availability

  2. Network connection errors

    • Verify internet connection
    • Check if PokéAPI (pokeapi.co) is accessible
    • Consider firewall/proxy issues

  3. MCP protocol errors

    • Ensure MCP library is properly installed
    • Check that client supports MCP version 1.0+
    • Verify JSON formatting in requests

Performance Notes

  • First request for each Pokémon may be slower (API fetch)
  • Subsequent requests use cached data for speed
  • Battle simulations are computed locally (fast)

Development

Adding New Features

New Status Effects:

  1. Add to StatusEffect enum
  2. Implement logic in process_status_effects()
  3. Add application logic in battle loop

New Battle Mechanics:

  1. Modify damage calculation in calculate_damage()
  2. Update battle simulation loop as needed
  3. Add new parameters to tool schemas

Additional Data Sources:

  1. Extend Pokemon dataclass
  2. Update fetch_pokemon_data() method
  3. Modify resource responses

Testing

Test the server using any MCP-compatible client:

# Test Pokemon data retrieval
{
  "method": "tools/call",
  "params": {
    "name": "get_pokemon_data",
    "arguments": {"name": "ditto"}
  }
}

# Test battle simulation
{
  "method": "tools/call", 
  "params": {
    "name": "simulate_battle",
    "arguments": {"pokemon1": "mewtwo", "pokemon2": "mew"}
  }
}

License

This project is for educational purposes. Pokémon is a trademark of Nintendo/Game Freak/Creatures Inc.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test with multiple Pokémon and battle scenarios
  5. Submit a pull request

Happy Training, Pokémon Masters! 🎮⚡