Vizier Yu-Gi-Oh! MCP

A Model Context Protocol server for Yu-Gi-Oh! card data: cards, prices, printings, banlists (historical + cross-format), official rulings, comprehensive rules, card relations, and deck tools. Everything runs locally from a single SQLite database with embedded vector search — no network calls at query time.

Features

• Cards: lookup by exact id or fuzzy-matched name, keyword search with type/ATK filters, semantic (vector) search by effect description, archetype listing.

• Prices & printings: current market prices (cardmarket / tcgplayer / ebay / amazon), full printing history with rarities and prices.

• Banlists: snapshots for tcg, ocg, ocg-ae, ocg-cn, master-duel, rush, genesys, ocg-genesys, goat, edison; per-card status across all formats, historical diffs between snapshots.

• Rules & rulings: semantic search over the official Comprehensive Rulebook (380 sections) and over 2,650 official OCG rulings; per-card ruling lookup with live-fetch fallback.

• Relations: search/summon/destroy/target relations mined from card text, Fusion/Synchro/Xyz/Link/Ritual material requirements, reverse lookups, archetype support detection.

• Decks: validate a decklist against a format's banlist, analyze main/extra composition and archetype mix.

Requirements

• Python 3.11+

• ~1 GB disk for the embedding model download; the built database is ~75 MB

• ~2 GB RAM during the build (embedding model); much less at query time

The database path and data directory can be overridden with VIZIER_DB_PATH and VIZIER_DATA_DIR environment variables (the default is <package root>/data/).

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e .

Building the database

The build ingests cached API data (data/cache/) and the reference projects (ref/, policy/) into data/vizier.db. No network is required unless you pass --fetch.

# full build including embeddings (slow: ~15-20 min CPU for 17.6k vectors)
python scripts/build_db.py

# faster variants
python scripts/build_db.py --no-embed      # skip vector embeddings (no semantic search)
python scripts/build_db.py --skip-cards    # skip card ingestion, re-embed only
python scripts/build_db.py --fetch         # download fresh API payloads first

--fetch downloads the card dump from YGOPRODeck. Note: the live API currently returns HTTP 403, so the cached dump in data/cache/ is authoritative. If the API is unreachable the build uses the cache.

Running the server

python -m vizier_mcp

The server speaks MCP over stdio. There is also a console script:

vizier-mcp

Client configuration

Point any MCP client at the installed command. The server name is vizier-yugioh.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "vizier-yugioh": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "vizier_mcp"]
    }
  }
}

Generic clients

{
  "mcpServers": {
    "vizier-yugioh": {
      "command": "/path/to/.venv/bin/vizier-mcp",
      "args": []
    }
  }
}

Use absolute paths to the venv. The DB path is resolved relative to the package location (or VIZIER_DB_PATH), not the CWD.

Tools

filter_type examples: monster, spell, trap, effect, fusion, link, pendulum, tuner, normal monster, normal spell, quick-play, counter trap, equip, field, ritual. Multi-word filters match the exact subtype.

Combo creation

The server ships a built-in combo-creation playbook that turns line-building into a deterministic breadth-first process: enumerate every possible action, expand, deepen, prune, record, repeat.

1. combo_guide() — load the playbook (also available as the combo prompt). It defines a combo-state JSON schema, the 6-step protocol, per-card enumeration checklists, tool routing, hard/soft OPT discipline, lock detection, and termination criteria.

2. card_combo_profile() — for any card you consider: summoning options (normal/tribute/pendulum/self-special), every effect with activation kind + once-per-turn status + action verbs, lock/restriction sentences, its full relation graph (searches/summons/destroys/targets/materials), materials it requires, and monsters it can be material for (named + archetype-wide).

3. board_options() — one call that returns EVERY legal next play from the current board, archetype-agnostic: all extra-deck summons (the full ~2,300-monster pool, not just the deck's archetype), every hand monster's plays (normal summon / self-special / pendulum scale), every search/add effect with its targets (archetype targets list top-ranked members), the pendulum summon range, and active/pending locks. This is the anti-tunnel-vision tool: the model must not restrict itself to in-archetype candidates.

4. line_search() — server-side bounded breadth-first search from the current board to a goal (field_levels, field_count, no_locks, reach_field, reach_hand). Returns complete multi-step lines, so the model plans several steps deep instead of one move at a time.

5. extra_deck_options() — paste your current field (plus hand/graveyard/extra deck and format) and get every Fusion/Synchro/Xyz/Link/Ritual monster whose material requirement is satisfiable, with the exact material reasoning for each candidate.

Example — two Level 4 D/D monsters on field:

extra_deck_options(field=["D/D Savant Copernicus", "D/D Ark"], summon_types="xyz")
→ options include D/D/D Wise King Solomon ("2 Level 4 D/D monsters")

Best-effort material checks are validated against the full relation graph; always confirm borderline candidates with get_card_materials before finalizing a line.

Resources

URL-encode resource parameters containing spaces (rules://damage%20step).

Database layout

data/vizier.db — SQLite with sqlite-vec extension. Key tables:

• cards — one row per card with computed type flags (is_monster, is_quickplay_spell, ...)

• card_sets, card_prices — printings and market prices

• card_ban_status, banlist_history — current status per format + historical snapshots

• relations — card-to-card effect relations with types

• rulebook_chunks, rulings — rules and rulings text

• card_vec, rule_vec, ruling_vec — embedding tables for semantic search

• meta — build timestamp and counts

Data sources

• Cards / prices / banlists: YGOPRODeck bulk API (cached in data/cache/)

• Rules: official Comprehensive Rulebook (ref/yugioh_comprehensive_rulebook/)

• Rulings: official OCG rulings Q&A list + YGOPEDIA fallback

• Policy: tournament policy documents (policy/)

Tests

python -m pytest tests/ -q

Runs 32 smoke tests against an in-process server client, covering every tool and resource.