Pokemon Champions Battle Assistant - MCP Server

This project is a Model Context Protocol (MCP) server for the Pokemon Champions Battle Assistant, built using @hono/mcp and the @modelcontextprotocol/sdk.

It allows LLMs (like Claude) to query live battle statistics and perform damage calculations directly on your local system or remote host.

🛠 Setup & Installation

1. Requirements

• Node.js v20+

• The repository PokemonChampions_Battle-assistant-tool cloned and populated with databases.

2. Install dependencies

In the root directory, run:

npm install

3. Build & Start the Server

To compile the TypeScript code and start the Hono server:

# Start in development mode (with hot-reloading)
npm run dev

# Or build and run the production server
npm run build
npm start

The server will start listening on http://localhost:8787.

Related MCP server: Pokemon Showdown MCP Server

🔌 Connecting to an MCP Client (e.g., Claude Desktop)

To connect Claude Desktop to your local Hono MCP server, add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "pokemon-champions": {
      "url": "http://localhost:8787/mcp"
    }
  }
}

🧰 Available Tools

Once connected, the following tools will be made available to your LLM:

1. get_pokemon_metadata

• Description: Returns base stats, types, English name, and ID of a given Pokemon.

• Parameters:

  • pokemon_name (string, required): Japanese or English name of the Pokemon (e.g., "ガブリアス", "garchomp").

2. get_battle_statistics

• Description: Returns popularity statistics of moves, items, natures, ev spreads, and abilities for a specific Pokemon in the current environment.

• Parameters:

  • pokemon_name (string, required)

  • format ("Singles" | "Doubles", default: "Doubles")

  • season (string, optional)

3. calculate_damage

• Description: Performs a precise Level 50 damage calculation between two Pokemon, factoring in nature, stats, items (like こだわりハチマキ, とつげきチョッキ), ranks, weather, and terrain.

• Parameters:

  • attacker (object, required): Attacker details (name, evs, nature, ranks, item, teratype).

  • defender (object, required): Defender details (name, evs, nature, ranks, item, teratype).

  • move (string, required): Move name (e.g., "じしん").

  • environment (object, optional): Weather and Terrain settings.

📁 Key Code Files

• package.json — Project configuration and dependencies.

• tsconfig.json — TypeScript settings.

• src/index.ts — The MCP server implementation.