PokeMCP is a Python-based MCP server that exposes Pokémon data fetched from the PokeAPI. It provides two primary tools for clients: get_pokemon_info and simulate_battle. The get_pokemon_info tool returns comprehensive data for a given Pokémon, including base stats, types, abilities with their effects, up to 10 moves with their effects, and the evolution chain. The simulate_battle tool models a simple battle between two Pokémon using core mechanics such as stats, types, and status effects, and returns a structured battle log along with the winner. To use these tools, run the PokeMCP server in your environment (for example via uv), connect your MCP client (such as Claude, Cursor, or another MCP-enabled client), and invoke the tools by name with the required arguments. The server handles errors gracefully and will provide an informative error field when something goes wrong, such as an unknown Pokémon or a network issue.

Prerequisites:

• Python 3.11.4+ installed on your system
• Internet access to fetch dependencies from PyPI
• Basic knowledge of running Python scripts and MCP tooling

Installation steps:

1. Clone the repository: git clone https://github.com/ChiragAgg5k/poke-mcp.git cd poke-mcp

2. Create and activate a Python virtual environment (recommended): python -m venv venv

   On Windows:

   venv\Scripts\activate

   On macOS/Linux:

   source venv/bin/activate

3. Install dependencies (httpx for async HTTP requests and MCP framework): pip install httpx pip install mcp.server.fastmcp

4. Ensure your MCP server file is present. The development script shown in the README uses server.py at the repo root. If running locally, you can start the server with: uv run mcp dev server.py

   or simply execute the Python script directly if you prefer:

   python server.py

5. Run the server: uv run mcp dev server.py

   or

   python server.py

6. Connect an MCP client (e.g., Claude or Cursor) and enable the poke-mcp server, then start issuing tools like get_pokemon_info and simulate_battle.

Notes and tips:

• The server relies on the PokeAPI for data; network issues may affect responses. The tooling includes error fields when Pokémon are not found or when there are connectivity problems.
• get_pokemon_info returns base_stats, types, abilities with effects, moves with effects (up to 10 moves), and the evolution chain. Ensure the Pokémon name is provided in lowercase or case-insensitive form.
• simulate_battle uses basic mechanics to determine a winner and returns a battle_log with turns and outcomes. This is a simplified model intended for demonstration.
• If you plan to deploy in production, consider caching frequent queries to reduce API calls and improve response times.
• Environment variables can be used to configure API endpoints, timeouts, or MCP-specific settings. The current setup shows an empty env block in the mcp_config, which you can populate as needed.