PokeMCP

# PokeMCP PokeMCP is an MCP (Modular Command Platform) server that provides detailed Pokémon information by integrating with the [PokeAPI](https://pokeapi.co/). 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 - Python 3.11.4+ - [httpx](https://www.python-httpx.org/) (for async HTTP requests) - [mcp.server.fastmcp](https://github.com/microsoft/mcp) (for MCP server framework) ## Installation 1. Clone this repository: ```bash git clone https://github.com/ChiragAgg5k/poke-mcp.git cd poke-mcp ``` 2. Install dependencies using [uv](https://github.com/astral-sh/uv): ```bash uv sync ``` ## Usage ### Development Server Run the server using uv (ensure you have the required MCP infrastructure): ```bash uv run mcp dev server.py ``` ### Connecting with Claude Run the following command to connect with Claude: ```bash uv run mcp install server.py ``` Result should look like this: ```bash 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* <img src="assets/claude_get_pokemon_info.png" alt="Claude with PokeMCP" width="500"> *Simulate Battle* <img src="assets/claude_simulate_battle.png" alt="Claude with PokeMCP" width="500"> Learn how to connect the server with other MCP clients like Cursor [here](https://docs.cursor.com/context/model-context-protocol). ## 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: ```json { "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: ```json { "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](https://pokeapi.co/) and is intended for educational and non-commercial use.