lorcana-mcp

MCP server that connects Claude to Disney Lorcana card data. Export your collection from TCGPlayer, hand it to Claude, and get it fully enriched with ink cost, stats, keywords, abilities, and format legality — plus a ready-to-import file for dreamborn.ink.

The simple version

What it does: plug this into Claude and it becomes a Disney Lorcana expert that knows your actual collection — no more tab-switching between TCGPlayer, dreamborn.ink, and a wiki.

Once it's connected, you can just talk to Claude like:

• 🗂️ "Enrich my collection at ~/Downloads/export.csv" — turns a bare TCGPlayer export into a full card database (cost, stats, keywords, abilities) plus a file ready to import into dreamborn.ink
• 🔎 "What's that card, big pete?" — finds cards even if you don't remember the exact name or spelling
• 🎴 "Show me cheap Evasive characters in Amber" — searches the entire card pool by color, cost, keyword, rarity, whatever
• 🎵 "Who can sing Be Our Guest for free?" — finds the best Singer combos for a song
• 📋 "Is this deck legal? 4x Goofy - Musketeer, 4x..." — checks curve, colors, and tournament legality of any deck list
• 💰 "What am I missing to finish this deck, and what would it cost?" — compares a deck list to your collection and prices the gap with live market data
• 🏗️ "Build me a Core Constructed Amber/Sapphire deck" — automatically assembles a legal, curve-balanced decklist from your collection, an ideal build priced to complete, or a full market build
• ✅ "Is my collection data still accurate?" — audits your CSV against live card data and flags anything stale

Everything reads from public card APIs plus your own exported CSV — no account, no login, nothing to configure.

Get it running in under a minute

Claude Desktop — one click: download lorcana-mcp.mcpb and double-click it (or Settings → Extensions → Install extension…). No terminal, no Python install, nothing to configure.

Everything else — one command:

1. Connect it (uvx fetches it on demand — install uv first, or pip install lorcana-mcp and drop the uvx):

claude mcp add lorcana -- uvx lorcana-mcp serve

Using Claude Desktop config, Cursor, VS Code, Windsurf, Cline, or Zed instead? Every client is covered in docs/INSTALL.md.

2. Talk to it: Export your collection from TCGPlayer (My Account → My Collection → Export), then just say:

"Enrich my collection at /path/to/your/export.csv"

That's it — Claude does the rest. Everything below is reference detail for when you want more control.

Tools

Twelve tools are available in Claude once the server is running:

Listed on

Install

You don't have to install anything if you use uvx (below) or the Claude Desktop bundle. To install the package explicitly:

pip install lorcana-mcp
# or:  uv tool install lorcana-mcp

From source:

git clone https://github.com/IcaroBichir/lorcana-mcp
cd lorcana-mcp
pip install .

Claude Desktop bundle: lorcana-mcp.mcpb on the releases page — a one-click install that bundles its own runtime. Built from packaging/mcpb/.

Add to your client

lorcana-mcp is a local stdio server — it runs on your machine, no hosting or API key. docs/INSTALL.md is the full guide, with copy-paste config for every client. The short version:

Claude Code (CLI)

claude mcp add lorcana -- uvx lorcana-mcp serve

Claude Desktop (manual config)

Easiest is the one-click bundle. To wire it up by hand instead, edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\, or Settings → Developer → Edit Config):

{
  "mcpServers": {
    "lorcana": {
      "command": "uvx",
      "args": ["lorcana-mcp", "serve"]
    }
  }
}

Use "command": "lorcana-mcp", "args": ["serve"] if you installed with pip rather than uv. Fully quit and reopen Claude Desktop after saving.

Usage

Once the server is connected, just talk to Claude naturally. No slash commands needed.

Enrich a collection

Export your collection from TCGPlayer → My Collection → Export CSV, then:

"Enrich my collection at /Users/me/Downloads/Lorcana_063026.csv"

Claude will fetch card data from the APIs and write two files next to your input:

• enriched_Lorcana_063026.csv — your collection with 10 new columns
• dreamborn_Lorcana_063026.csv — ready to import at dreamborn.ink

On re-runs, pass the previous enriched file as a cache to skip already-seen cards:

"Enrich /Users/me/Downloads/Lorcana_new.csv using /Users/me/lorcana/enriched_Lorcana_old.csv as cache"

To refresh prices on demand without re-exporting from TCGPlayer:

"Re-enrich my collection at /Users/me/lorcana/enriched_Lorcana_063026.csv and refresh prices"

refresh_prices=True overwrites each row's TCG Market Price with a live tcgcsv.com lookup for that exact printing — useful when an enriched CSV's prices are stale.

Look up a card

"Look up Mirage - Super Recruiter"

"What are the stats on Alma Madrigal - Heart of the Family?"

"Is Will o' the Wisp legal in Core?"

Returns: ink color, cost, type, subtypes, STR/WIL/Lore, inkable status, keywords, full ability text, format legality, and a card image URL.

Resolve an informal or misspelled card name

"Find the card 'goofy musketeer'"

"What's that card 'big pete'?"

"Look up 'elsa' — not sure which version"

Tokenizes the query and scores it against every card's name and subtitle, tolerating missing dashes, missing subtitles, word order, and minor typos. Returns full detail for a single confident match, a ranked top-3 with confidence scores when several cards are plausible (e.g. a bare name matching every printing of that character), or nothing if the query doesn't resemble any card.

Search the full card pool

"Show me all Evasive characters in Amethyst that cost 3 or less"

"Find Toy characters"

"Search for Rare Steel cards from Wilds Unknown"

Filters: ink color(s), card type (Character / Action / Item / Location / Song), rarity, set name, cost range, keyword, ability text substring, and subtype — all combinable, plus pagination (offset + limit). Results are grouped by ink color and sorted by cost.

Find who can sing a song

"Which characters can sing Be Our Guest?"

"Show me Amber characters that can sing a cost-7 song"

"Who can sing Friends on the Other Side, and which ones do I own?" (pass your enriched collection CSV)

A character can sing a song if its printed cost meets the song's cost outright, or it has a matching Singer X keyword — Singer lets a cheap character punch above its actual cost for singing purposes only. Results split into Singer-keyword "discount" picks (highest Singer value, then cheapest actual cost) and plain cost-qualifiers (cheapest first). Pass collection_csv to flag ownership.

Filter your collection by format

"Which of my cards are legal in Core Constructed?"

"Show me my Infinity-legal cards grouped by ink color"

"What Poorcana-legal cards do I have in Amber?"

Valid formats: core, infinity, core_zh, core_ja, poorcana

Poorcana filtering uses the Rarity column in your enriched CSV (Common + Uncommon only) — no API call needed.

Core/Infinity/regional legality comes from duels.ink, which tracks the current rotation for each region.

Audit an existing enriched file

"Audit my collection at /Users/me/lorcana/enriched_collection.csv"

Useful after a new set releases or if a card's data looks wrong. Compares every non-promo card against live API data and reports field-by-field discrepancies.

Analyze a deck list

"Analyze this deck: 4x Goofy - Musketeer, 4x Elsa - Spirit of Winter, ..." (paste a full list, one card per line)

Accepts 4x Card Name or 4 Card Name; quantity defaults to 1 if omitted. Lines starting with # or // are treated as comments.

Returns: ink curve (1-2/3-4/5-6/7+ cost brackets), inkable vs. uninkable count, color split, card type split, an estimated lore-per-turn (sum of Character lore values), a Core Constructed legality check (60-card minimum, max 4 copies of any card, at most 2 ink colors), and any card names that couldn't be resolved.

Check what a deck list is missing

"What am I missing to build this deck?" (paste the deck list and point me at your collection CSV)

"How much would it cost to finish this Amber/Steel list?"

Same deck list format as analyze_deck. Cross-references against your enriched collection CSV, then splits results into cards you already have enough of and cards you're missing or short on. For cards you're short on (own at least one printing already), the cost comes straight from the CSV's own TCG Market Price column — no network call needed. Only cards you own zero copies of fall back to a live TCGPlayer lookup via tcgcsv.com (cheapest printing across all sets/rarities, since gameplay is identical), and even then only if at least one card actually needs it. Live price data is cached for 24h, so the first call that needs it takes a bit longer while it warms up.

Enriched columns

The enricher adds these 10 columns to the raw TCGPlayer export:

Data sources

Card data is fetched live and cached locally for 24 hours at ~/.cache/lorcana-mcp/. If LorcanaJSON is unreachable, the server falls back to a bundled card snapshot (lorcana_mcp/data/allcards_fallback.json.gz, refreshed each release) and warns once that data may be stale. Manage the cache with the CLI:

lorcana-mcp cache stats   # show entry count, expiry status, and file size
lorcana-mcp cache clear   # delete all cached responses (fresh fetch on next use)

Supported sets

New sets are picked up automatically via LorcanaJSON as long as the set name is added to the internal mapping. Open an issue if a new set isn't resolving.

TCGPlayer export format

Go to TCGPlayer → My Account → My Collection → Export. The raw file has columns like Product Name, Set Name, Number, Rarity, Condition, Printing, and Add to Quantity (this is the real owned-quantity column — Total Quantity is always blank in exports).

Promo cards: resolved automatically where possible. dreamborn.ink's bulk import represents a promo as (Set Number, Card Number) where Set Number is the LJ set the promo drop is tied to and Card Number is the full "N/Series" string (e.g. "57/P3") — verified against a real dreamborn export, not just its card-browser display (an earlier attempt based on the display alone silently corrupted imports; see CHANGELOG.md's 0.2.2/0.2.3 entries). Any promo not yet in that map still needs manual entry via dreamborn.ink's card search after importing the rest.

CLI reference

lorcana-mcp --version
lorcana-mcp serve          Start the MCP server (stdio)
lorcana-mcp cache stats    Show cache info
lorcana-mcp cache clear    Clear cached API responses

Staying up to date

The card data is always live (fetched from public APIs, cached 24h) — but the bundled metagame snapshot (get_meta) and any tool/behaviour changes only move when you update the package:

pip install -U lorcana-mcp        # or: uv tool upgrade lorcana-mcp

Claude Desktop .mcpb users: re-download lorcana-mcp.mcpb and reinstall — the bundle pins an exact version and does not auto-update. Restart your MCP client after updating so it reconnects to the new server.

Get told when there's a new release:

• The server checks PyPI about once a day (fail-silent, cached, one request) and, if it's behind, prints a one-line notice to stderr on startup — visible in Claude Code's MCP logs / Claude Desktop's log files — and appends a note to get_meta's output. Opt out with LORCANA_MCP_NO_UPDATE_CHECK=1 in the server's env.
• Or watch the repo: Watch → Custom → Releases, or subscribe to the Atom feed https://github.com/IcaroBichir/lorcana-mcp/releases.atom.

Development

git clone https://github.com/IcaroBichir/lorcana-mcp
cd lorcana-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

355 tests, no network calls required. CI runs the full suite on Python 3.11, 3.12, and 3.13 on every pull request and on push to main (see .github/workflows/tests.yml).

License

MIT — see LICENSE.

🤖 CLAUDE READ THIS

If you're an AI agent (Claude or otherwise) with this MCP server connected, read this section before making tool calls. It's the fast path to using this correctly.

Which tool to call

Hard rules

1. Always pass absolute paths for csv_path / input_path / collection_csv. Relative paths resolve against the server process's cwd, not the user's — this fails silently or points at the wrong file. If you don't have an absolute path, ask the user or find the file first.
2. Default to resolve_card over lookup_card unless the user gave you a name you're confident is exact and correctly spelled. When in doubt, resolve_card is strictly more forgiving and costs nothing extra.
3. Never hand-roll price lookups. find_song_synergies, what_am_i_missing, and build_deck already call tcgcsv.com internally with 24h caching and cheapest-printing logic. Don't curl TCGPlayer or scrape prices yourself.
4. Gameplay is identical across printings (base, Enchanted, Epic, promo — same name, cost, stats, abilities). Every price-aware tool already picks the cheapest printing automatically; don't second-guess a suspiciously low result, and don't treat rarity as a gameplay signal. Use list_printings when the user needs the per-printing breakdown (which one is legal in a format, which is cheapest, whether it got an Enchanted).
5. If a user says data looks wrong or stale, suggest lorcana-mcp cache clear before assuming a tool is broken — card and price data is cached 24h.
6. Ambiguous tool output is a feature, not an error. resolve_card and find_song_synergies can return a ranked "did you mean" list instead of a single answer — present it to the user rather than guessing which one they meant.
7. build_deck is a curve/keyword-value heuristic, not a synergy engine. It doesn't detect multi-card combos (Merlin/Mim bounce, Steelsong, etc.) — don't present its output as a finished, tournament-tuned decklist. Treat it as a strong starting point to review and adjust, not a final answer.

Known gotchas (found the hard way — see CHANGELOG.md)

• Product ID (CSV column 1) ≠ TCGplayer Id (column 2). Only Product ID matches external pricing APIs (LorcanaJSON's externalLinks.tcgPlayerId, tcgcsv.com's productId). Column 2 is an unrelated secondary ID — if you're ever writing custom code against this data, matching on it silently returns zero results.
• Promo cards resolve via PROMO_DREAMBORN_ROW/PROMO_DREAMBORN_ROW_BY_NUMBER (api.py) — verified against a real dreamborn.ink export, not its card-browser display (an earlier browser-based guess silently corrupted a real import; CHANGELOG.md 0.2.2). A promo's dreamborn Card Number is the full "N/Series" string, not split into a separate series field — don't re-split it if extending this map. Anything not yet in the map still needs manual entry via dreamborn.ink's search after importing.
• Duplicate-looking rows in search results are printings, not bugs — search_cards and find_song_synergies already deduplicate alt-art/Enchanted reprints by name internally, so don't be surprised the count is lower than you'd expect from a raw card list.

If you're modifying this codebase

• Run pytest before and after any change — 355 tests, all network-free (external calls are mocked; tests/conftest.py also disables the PyPI update check).
• Code layout: pure/testable logic lives in api.py (card data + fuzzy matching + pricing), deck.py (deck list parsing/analysis), enricher.py (CSV pipeline), meta.py + tournaments.py (bundled metagame/tournament snapshot), and update_check.py (PyPI version check). server.py only wraps those as MCP tools and formats output — keep it that way rather than putting logic directly in tool functions. lorcana_mcp/data/allcards_fallback.json.gz is the offline card-data fallback (refresh with scripts/update_fallback_snapshot.py).
• A release bumps the version in four files (pyproject.toml, server.json, packaging/mcpb/pyproject.toml — both its version and the lorcana-mcp== pin — and packaging/mcpb/manifest.json), adds a CHANGELOG.md entry, and updates this README + docs/INSTALL.md if tool behavior changed. Check git log for the chore: release X.Y.Z pattern.
• Publishing is a separate, explicit step (python -m build, twine upload, mcp-publisher publish) — never assume a version bump in pyproject.toml means it's live on PyPI or the registry. Check before telling a user a feature is "available."