bringfour

Give your AI assistant a competitive Pokémon brain. An MCP server (plus a local web dashboard) that turns Claude, Cursor, or any MCP client into a VGC teambuilding partner — real usage stats, real damage calcs, and threat reports grounded in math instead of type-chart guessing.

🚧 Pre-1.0: the npm publish is imminent — until it lands, use the from-source setup; everything works today.

<!-- TODO(launch): record docs/threat-report.gif — paste team → threat cards -->

Ask "what beats my trick room team?" and get back OHKO/2HKO lines computed with @smogon/calc against the top meta Pokémon at their actual most common spreads — not vibes. Defaults to the current official format (Pokémon Champions, Regulation Set M-B); SV Regulation I and other formats are one format parameter away.

Quick start

Claude Code

claude mcp add bringfour -- npx -y bringfour

Claude Desktop / Cursor

{
  "mcpServers": {
    "bringfour": {
      "command": "npx",
      "args": ["-y", "bringfour"]
    }
  }
}

From source

git clone <this repo> && cd <repo> && npm install

The repo ships a project-scoped .mcp.json, so Claude Code picks the server up automatically when working in this directory. For other clients, run npx tsx src/index.ts (stdio transport).

Tools

Tool	What it does
meta_snapshot	Top meta Pokemon with usage/win rates for a format.
pokemon_deep_dive	One Pokemon's common items, abilities, moves, spreads, natures, Tera types (SV), teammates.
analyze_team	Calc-backed threat report: for the top N meta Pokemon at their most common sets, real OHKO/2HKO threats against your actual EVs, plus speed tiers and speed-control flags (Tailwind/Trick Room/Icy Wind...).
calc_damage	Damage calc via @smogon/calc. Unspecified fields auto-fill from meta data; every assumption is echoed so the agent can override and re-call.
save_team / list_teams	Store Showdown-export pastes as plain text, so "analyze my worlds team" works without re-pasting.

Web dashboard

npm run ui        # http://localhost:4747

A local dashboard (dark, sprite-heavy, no build step) over the same data layer as the MCP tools:

• Threats — pick a saved team, get the calc-backed threat report as cards with OHKO/2HKO badges, damage bars, a speed ladder, and speed-control flags.
• Damage Calc — attacker/defender panels that pre-fill the most common meta set (grayed-italic until you override a field), live results, field conditions, swap sides.
• Teams — create/edit Showdown pastes, or import from a pokepast.es link.
• Meta / deep-dive — sortable usage table; click through to per-Pokemon items, moves, spreads, natures, and teammates.

Where data lives

Running from a checkout (or any directory containing a teams/ folder) keeps teams in ./teams/ and the 24h usage-data cache in ./.cache/, as always. Running via npx/global install falls back to ~/.bringfour/. Override with:

Env var	Effect
VGC_TOOLS_HOME	Base directory for both (<home>/teams, <home>/cache)
VGC_TEAMS_DIR	Teams directory only
VGC_CACHE_DIR	Cache directory only

Data sources & behavior

• Pikalytics (pikalytics.com) is the primary usage source — in-game ranked battle data for Champions, HOME battle data for SV. Pikalytics asks for attribution when citing its stats; every tool response carries it.
• Smogon usage stats (smogon.com/stats, Showdown ladder chaos JSON) are the automatic fallback when Pikalytics lacks a format.
• Usage dumps are monthly; the service walks back up to 7 months to find the newest published data, and caches responses for 24h.
• Teams are plain Showdown-export text files — edit them freely.

Champions caveats (honest-approximation zone)

• Champions EVs run 0–32 per stat. For damage/stat math they are mapped onto the classic 0–252 scale (×8, capped); every calc that does this says so in its assumptions. Treat very close rolls with caution.
• Champions Mega formes ("Charizard-Mega-Y") mostly exist in @smogon/calc's data already; anything the calc doesn't know is reported explicitly instead of guessed at.

Roadmap

• v2: EV-spread optimization; tournament results/team lists via the documented Limitless API.
• Hosted copilot: a web app where a frontier model writes full team coaching reports over these tools — in design, gated on this repo proving demand. Star the repo if you want it to exist.

Support

<!-- TODO(launch): add GitHub Sponsors / Ko-fi link --> If this saves you a ladder session of scouting, a star is the best signal you can send.

License & legal

MIT — see LICENSE.

Unofficial fan tool — not affiliated with, endorsed, or supported by Nintendo, Creatures Inc., GAME FREAK, or The Pokémon Company. Pokémon and all respective names are trademarks of their owners. Usage data courtesy of Pikalytics (attribution requested) and Smogon usage stats; damage math by @smogon/calc (MIT); sprites served from Pokémon Showdown's public sprite sets.