Pokémon VGC Damage Calculator MCP Server

A server built using Model-Context Protocol (MCP) that provides AI agents a standardized interface for performing Pokémon damage calculations using the @smogon/calc package.

Features

MCP-compliant server with TypeScript and the official MCP SDK
Accurate damage calculations powered by the community-vetted @smogon/calc library
Comprehensive input handling for Pokémon stats, abilities, items, moves, and field conditions
Error handling for invalid Pokémon names, moves, and input validation
Vercel deployment ready with zero-config deployment support

Prerequisites

Node.js 18+
npm

Installation

npm install -g pokemon-vgc-calc-mcp

Development

npm run build  # Build TypeScript
npm run test   # Run test calculation

MCP Client Configuration

Configure your MCP client (Claude Desktop, Cursor, etc.):

Using remote npm package:

{
  "mcpServers": {
    "pokemon-calc": {
      "command": "npx",
      "args": ["pokemon-vgc-calc-mcp"],
      "env": {}
    }
  }
}

Local development:

Clone repo locally, build the project and then configure MCP client:

$ git clone git@github.com:jpbullalayao/pokemon-vgc-calc-mcp.git
$ npm install
$ npm run build

{
  "mcpServers": {
    "pokemon-calc": {
      "command": "node",
      "args": ["path/to/pokemon-vgc-calc-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Tools Available

The server exposes one primary tool: calculateDamage

Tool: calculateDamage

Calculates battle damage between an attacking and defending Pokémon.

Input Parameters:

attacker: Pokémon object with species, level, stats, ability, item, etc.
defender: Pokémon object with species, level, stats, ability, item, etc.
move: Move object with name and optional critical hit flag
field: Field conditions including weather, terrain, and side effects

Output:

description: Human-readable calculation result
damage: [min, max] damage range
koChance: Knock-out probability description
fullResult: Complete result object from smogon/calc

Example Usage

When called by an MCP client, the tool accepts parameters like:

{
  "attacker": {
    "species": "Pikachu",
    "level": 50,
    "ability": "Static", 
    "item": "Light Ball",
    "nature": "Timid",
    "evs": { "spa": 252, "spe": 252, "hp": 4 }
  },
  "defender": {
    "species": "Charizard",
    "level": 50,
    "ability": "Blaze"
  },
  "move": {
    "name": "Thunderbolt"
  },
  "field": {
    "gameType": "Singles"
  }
}

Output:

**252 SpA Light Ball Pikachu Thunderbolt vs. 0 HP / 0 SpD Charizard: 198-234 (107 - 126.4%) -- guaranteed OHKO**

Damage: 198-234
KO Chance: guaranteed OHKO

Testing

Local MCP Server Testing

You can test the local MCP server using the MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector node path/to/pokemon-vgc-calc-mcp/dist/index.js

Test Input Example

Use the following input to test the calculateDamage tool:

{
  "attacker": {
    "species": "Chien-Pao",
    "nature": "Jolly",
    "evs": {
      "atk": 252,
      "spe": 252,
      "hp": 4
    },
    "level": 50
  },
  "defender": {
    "species": "Flutter Mane",
    "nature": "Modest",
    "evs": {
      "hp": 164,
      "def": 100
    },
    "level": 50
  },
  "move": {
    "name": "Icicle Crash"
  },
  "field": {}
}

Expected Output

**252 Atk Sword of Ruin Chien-Pao Icicle Crash vs. 164 HP / 100 Def Flutter Mane: 126-148 (83.4 - 98%) -- guaranteed 2HKO**

Damage: 126-148
KO Chance: guaranteed 2HKO

Project Structure

src/
├── index.ts       # Main MCP server implementation
├── calculator.ts  # Damage calculation wrapper
└── types.ts       # TypeScript type definitions

Author's Note

Interested in the progress of this project? Feel free to follow the repo for live updates!

If you need to get a hold of me regarding this project, feel free to either:

email me at professor.ragna@gmail.com
tweet me @professorragna

If you're interested in helping to fund this project, you can support me here. Any and all support is greatly appreciated!

License

MIT

You must be authenticated.

security – no known vulnerabilities

license - not found

quality - confirmed to work

Tools

calculateDamage

An MCP-compliant server that enables AI agents to perform accurate Pokémon battle damage calculations using the Smogon calculator, supporting comprehensive input handling for Pokémon stats, moves, abilities, and field conditions.

Related MCP Servers

FastPostgresMCP
llm-graph
A
security
A
license
A
quality
A blazing fast MCP server that enables AI agents to interact with multiple PostgreSQL databases, providing functionality to list tables, inspect schemas, execute queries, and run transactions.
Last updated -
4
58
TypeScript
MIT License
MCP Pokemon Server
sarathvad1811
-
security
F
license
-
quality
An MCP server implementation that enables users to interact with the PokeAPI to fetch Pokemon information through natural language queries.
Last updated -
Python
RAGmonsters Custom PostgreSQL MCP Server
LostInBrittany
-
security
F
license
-
quality
A domain-specific MCP server that provides optimized API access to the RAGmonsters fictional monster dataset, enabling more efficient and secure interactions compared to generic SQL queries.
Last updated -
1
JavaScript
PokeMCP
ChiragAgg5k
-
security
F
license
-
quality
An MCP server that provides detailed Pokémon information by integrating with the PokeAPI, allowing users to fetch comprehensive data about Pokémon and simulate battles.
Last updated -
2
Python

View all related MCP servers

Pokémon VGC Damage Calculator MCP Server