hearthstone-oracle

Hearthstone MCP server with card search, deck analysis, and strategy coaching. Gives LLMs access to every Hearthstone card plus built-in strategy knowledge for deck building and gameplay advice.

Features

Complete card database from HearthstoneJSON — every collectible card, auto-updated
Deck decoding and analysis — paste a deck code, get full card list, mana curve, and archetype breakdown
Strategy knowledge — archetypes, class identities, matchup dynamics, and game concepts
9 MCP tools — search, lookup, decode, analyze, coach

Quick Start

claude mcp add hearthstone-oracle -- npx -y hearthstone-oracle

Card data is downloaded automatically from HearthstoneJSON on first run and stored locally in ~/.hearthstone-oracle/. No API key required.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Tools

Tool	Description
`search_cards`	Search cards by name, text, class, cost, type, rarity, set, or keyword
`get_card`	Get complete details for a specific card with fuzzy matching
`get_keyword`	Look up keyword/mechanic definitions with related cards
`decode_deck`	Decode a deck code into full card list with mana curve
`analyze_deck`	Analyze a deck's archetype, gameplan, strengths, and matchup profile
`get_archetype`	Learn about deck archetypes (aggro, control, combo, midrange, tempo, value)
`get_class_identity`	Strategic identity of each Hearthstone class
`get_matchup`	Theoretical matchup dynamics between archetypes
`explain_concept`	Fundamental game concepts explained for Hearthstone

How It Works

Two-layer architecture:

Card data layer — Full card database from HearthstoneJSON, stored in a local SQLite database with FTS5 full-text search. Cards are fetched on first run and updated when newer game builds are available.
Strategy layer — Built-in strategy knowledge covering archetypes, class identities, matchup theory, and core game concepts. Enables the server to provide coaching and analysis, not just raw card data.