poke-mcp

ChiragAgg5k/poke-mcp

3.2

If you are the rightful owner of poke-mcp 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.

PokeMCP is a server that provides detailed Pokémon information by integrating with the PokeAPI.

Tools

  1. get_pokemon_info

    Fetches detailed information about a Pokémon.

  2. simulate_battle

    Simulates a Pokémon battle between two Pokémon using core mechanics.

PokeMCP

PokeMCP is an MCP (Modular Command Platform) server that provides detailed Pokémon information by integrating with the PokeAPI. It exposes a tool to fetch comprehensive data about any Pokémon, including base stats, types, abilities (with effects), moves (with effects), and evolution chain.

Features

  • Fetches Pokémon base stats, types, and abilities (with effect descriptions)
  • Retrieves up to 10 moves per Pokémon, including move effects
  • Provides the full evolution chain for a given Pokémon
  • Handles errors gracefully and returns informative error messages

Requirements

Installation

  1. Clone this repository: 
    git clone https://github.com/ChiragAgg5k/poke-mcp.git
cd poke-mcp
  2. Install dependencies using uv: 
    uv sync

Usage

Development Server

Run the server using uv (ensure you have the required MCP infrastructure):

uv run mcp dev server.py

Connecting with Claude

Run the following command to connect with Claude:

uv run mcp install server.py

Result should look like this:

Added server 'poke-mcp' to Claude config   
Successfully installed poke-mcp in Claude app

Now you can use the poke-mcp MCP tools in Claude:

Get Pokemon Info

Simulate Battle

Learn how to connect the server with other MCP clients like Cursor here.

API

Tool: get_pokemon_info

Fetches detailed information about a Pokémon.

Arguments
  • pokemon_name (str): The name of the Pokémon (case-insensitive)
Returns

A dictionary with the following structure:

{
  "name": "pikachu",
  "id": 25,
  "base_stats": {
    "hp": 35,
    "attack": 55,
    ...
  },
  "types": ["electric"],
  "abilities": [
    {"name": "static", "effect": "May paralyze on contact."},
    ...
  ],
  "moves": [
    {"name": "thunder-shock", "effect": "Has a 10% chance to paralyze the target."},
    ...
  ],
  "evolution_chain": ["pichu", "pikachu", "raichu"]
}
Error Handling

If the Pokémon is not found or there is a network error, the response will include an error key with a descriptive message.

Tool: simulate_battle

Simulates a Pokémon battle between two Pokémon using core mechanics (stats, type, and status effects).

Arguments
  • pokemon1 (str): Name of the first Pokémon (case-insensitive)
  • pokemon2 (str): Name of the second Pokémon (case-insensitive)
Returns

A dictionary with the following structure:

{
  "pokemon1": "pikachu",
  "pokemon2": "charizard",
  "initial_hp": {
    "pikachu": 35,
    "charizard": 78
  },
  "battle_log": [
    "Turn 1:",
    "charizard uses mega-punch and deals 75 damage! (pikachu HP: 0)",
    "pikachu fainted!",
    "Winner: charizard!"
  ],
  "winner": "charizard"
}
Error Handling

If either Pokémon is not found or there is a network error, the response will include an error key with a descriptive message.

License

This project uses the PokeAPI and is intended for educational and non-commercial use.