Skip to main content
Glama
jpbullalayao

Pokémon VGC Damage Calculator MCP Server

by jpbullalayao
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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

Related MCP server: PokeMCP

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:

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

License

MIT

Available Tools

1 tool
calculateDamageC

Calculates the battle damage between an attacking and a defending Pokémon, considering their stats, abilities, items, and field conditions.

ParametersJSON Schema
NameRequiredDescriptionDefault
attackerYes
defenderYes
moveYes
fieldYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions what factors are considered but doesn't explain computational complexity, accuracy limitations, whether it's deterministic, or what the output format looks like. This leaves significant gaps for a complex calculation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently communicates the core functionality without unnecessary words. It's appropriately sized for a tool with this complexity level.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex calculation tool with 4 nested parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain the calculation methodology, output format, error conditions, or provide examples of proper usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and 4 complex parameters (attacker, defender, move, field), the description only vaguely mentions 'stats, abilities, items, and field conditions' without explaining parameter relationships, required data formats, or how these inputs map to the damage calculation. It fails to compensate for the complete lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('calculates') and resource ('battle damage'), and lists key factors considered (stats, abilities, items, field conditions). However, without sibling tools to differentiate from, it cannot achieve a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, prerequisites, or specific battle scenarios where it's applicable. The description only states what it does, not when it should be invoked.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool update
    • First observedcalculateDamage
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The tool's purpose is clearly defined and distinct by default.

Naming Consistency5/5

A single tool inherently has consistent naming, as there are no other tools to compare it against. The name 'calculateDamage' follows a clear verb_noun pattern.

Tool Count2/5

One tool is too few for a server named 'Pokémon VGC Damage Calculator MCP Server', which implies a domain requiring multiple operations like damage calculation, stat lookup, move effects, or team analysis. A single tool feels incomplete for the apparent scope.

Completeness2/5

The server is severely incomplete for its domain. While damage calculation is a core function, there are obvious gaps such as missing tools for retrieving Pokémon stats, moves, abilities, or handling team compositions, which are essential for a comprehensive VGC calculator.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • PokeMCP

    ChiragAgg5k
    F
    license
    B
    quality
    D
    maintenance
    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.
    2
    2
    -

  • pokemon-gen3-calc-mcp

    ptrst102
    F
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables accurate status and damage calculations for third-generation Pokémon games, including support for complex factors like weather, abilities, and items. It also provides tools for calculating optimal effort value (EV) distributions through brute-force damage matrix simulations.
    -

  • Poke-MCP

    Jalajil
    F
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that provides comprehensive Pokemon data and battle simulation capabilities to AI assistants. It enables users to access detailed stats, types, and moves while simulating battles with realistic mechanics like type effectiveness and status effects.
    -