lorcana-mcp

# lorcana-mcp

[![Tests](https://github.com/IcaroBichir/lorcana-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/IcaroBichir/lorcana-mcp/actions/workflows/tests.yml)
[![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/?q=lorcana)
[![mcp.so](https://img.shields.io/badge/mcp.so-lorcana--mcp-orange)](https://mcp.so/server/lorcana-mcp)
[![lorcana-mcp MCP server](https://glama.ai/mcp/servers/IcaroBichir/lorcana-mcp/badges/score.svg)](https://glama.ai/mcp/servers/IcaroBichir/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

**Claude Desktop — one click:** download [`lorcana-mcp.mcpb`](https://github.com/IcaroBichir/lorcana-mcp/releases/latest) 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](https://docs.astral.sh/uv/) first, or `pip install lorcana-mcp` and drop the `uvx`):
```bash
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](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:

| 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. |
| `list_printings`      | Lists every printing of a card — or every card sharing a character name — side by side: set, number(s), cost, stats, rarity, per-format legality, and cheapest market price. Optional `fmt` adds a ✓/✗ legality column. For "which printing of X is Core-legal / cheapest?". |
| `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). Also builds for `format="coconut"` — Ravensburger's multiplayer singleton beta (up to 3 ink colors, 1 copy of everything except your chosen Coconut's associated character at up to 4). A heuristic curve/keyword-value builder, not a synergy/combo detector. |
| `get_meta`            | Returns a hand-maintained Core Constructed metagame snapshot: every two-ink pair's tier, rough meta share, and playstyle, plus recent tournament results — optionally filtered to one pair (`ink_colors="Emerald,Steel"`). With `event=` ("nac", "asia", "kobe", …) returns that tournament's full standings and decklists instead. Not a live fetch — there's no free structured feed for this the way there is for card data — so it's a versioned snapshot bundled at release time, and says so explicitly in its own output. |

---

## Listed on

| Directory | Link |
|---|---|
| MCP Registry (official) | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/?q=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

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

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

From source:

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

**Claude Desktop bundle:** [`lorcana-mcp.mcpb`](https://github.com/IcaroBichir/lorcana-mcp/releases/latest) on the releases page — a one-click install that bundles its own runtime. Built from [`packaging/mcpb/`](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](docs/INSTALL.md) is the full guide**, with copy-paste config for every client. The short version:

| Client | Supported | How |
|---|---|---|
| Claude Desktop | ✅ | One-click [`.mcpb` bundle](https://github.com/IcaroBichir/lorcana-mcp/releases/latest), or config below |
| Claude Code | ✅ | `claude mcp add lorcana -- uvx lorcana-mcp serve` |
| Cursor · VS Code · Windsurf · Cline · Zed | ✅ | stdio config — see [docs/INSTALL.md](docs/INSTALL.md) |
| Any other stdio MCP client | ✅ | Command: `uvx lorcana-mcp serve` (or `lorcana-mcp serve` if pip-installed) |
| Claude.ai (web) · ChatGPT | ❌ | Those need a hosted remote server; this one is local-only — see [docs/INSTALL.md](docs/INSTALL.md#what-this-server-cant-do) |

### Claude Code (CLI)

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

### Claude Desktop (manual config)

Easiest is the [one-click bundle](https://github.com/IcaroBichir/lorcana-mcp/releases/latest). 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**):

```json
{
  "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:

>