lorcana-mcp

# lorcana-mcp

[![PyPI](https://img.shields.io/pypi/v/lorcana-mcp)](https://pypi.org/project/lorcana-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/lorcana-mcp)](https://pypi.org/project/lorcana-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/servers/io.github.IcaroBichir/lorcana)
[![mcp.so](https://img.shields.io/badge/mcp.so-lorcana--mcp-orange)](https://mcp.so/server/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](https://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

**1. Install it:**
```bash
pip install lorcana-mcp
```

**2. Connect it to Claude:**
```bash
claude mcp add lorcana -- lorcana-mcp serve
```
*(Using Claude Desktop instead? See [Add to Claude](#add-to-claude) below.)*

**3. 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

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

| Tool                  | What it does |
|-----------------------|---|
| `enrich_csv`          | Enriches a raw TCGPlayer export with Ink, Cost, Type, Subtypes, STR/WIL/Lore, Inkable, Keywords, and Abilities. Writes an enriched CSV and a dreamborn.ink-ready import file next to the input. `refresh_prices=True` also refreshes TCG Market Price with a live tcgcsv.com lookup. |
| `lookup_card`         | Looks up any card by name. Returns full stats, ability text, format legality, and card image URL. |
| `resolve_card`        | Fuzzy-resolves an informal, misspelled, or subtitle-less card name (e.g. "goofy musketeer", "elsa"). Returns a single confident match, a ranked top-3 to disambiguate, or nothing found. |
| `search_cards`        | Searches the full card pool by color, type, rarity, set, cost range, keyword, ability text, or subtype — with pagination. |
| `find_song_synergies` | Finds every character that can sing a given song (or a raw cost threshold), split into Singer-keyword discount picks and plain cost-qualifiers. Optionally flags which ones you own. |
| `filter_collection`   | Filters your collection to cards legal in a given format: `core`, `infinity`, `core_zh`, `core_ja`, or `poorcana`. |
| `audit_csv`           | Compares an enriched collection against live API data and reports any stale or wrong fields. |
| `analyze_deck`        | Analyzes a raw deck list (`4x Card Name` per line) for ink curve, inkable split, color split, card types, estimated lore/turn, and Core Constructed legality (60-card min, max 4 copies, ≤2 ink colors). |
| `what_am_i_missing`   | Compares a deck list against your collection: what you already own, what's missing or short, and a live TCGPlayer cost estimate (via tcgcsv.com) to complete it. |
| `build_deck`          | Automatically assembles a legal, curve-balanced ~60-card decklist for an ink pair/format, in one of 3 modes: `collection` (only cards you own), `ideal` (best deck regardless of ownership, priced to complete if you pass a collection CSV), or `market` (best deck, fully priced, ignoring ownership). A heuristic curve/keyword-value builder, not a synergy/combo detector. |

---

## Listed on

| Directory | Link |
|---|---|
| MCP Registry (official) | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/servers/io.github.IcaroBichir/lorcana) |
| mcp.so | [mcp.so/server/lorcana-mcp](https://mcp.so/server/lorcana-mcp) |
| PyPI | [pypi.org/project/lorcana-mcp](https://pypi.org/project/lorcana-mcp/) |

---

## Install

```bash
pip install lorcana-mcp
```

Or from source:

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

---

## Add to Claude

### Claude Code (CLI)

```bash
claude mcp add lorcana -- lorcana-mcp serve
```

### Claude Desktop

Find `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) and add:

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

Restart Claude Desktop after saving.

### Cursor / other MCP clients

Any client that supports stdio MCP servers can use `lorcana-mcp serve` as the command.

---

## 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](https://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)

A