Disney Lorcana MCP

Disney Lorcana MCP Server

Claude（または任意の MCP クライアント）で、Disney Lorcana TCGのカードを検索・分析し、デッキを構築できる MCP サーバーです。平易な英語でカードを検索し、ルールに基づくデッキ検証、インクカーブやキーワードの内訳を確認したり、Dreamborn／Pixelborn のデッキリストをインポート・エクスポートしたりできます。

ユニークなカードは 2,506 枚（別イラストやプロモを含む印刷版は 3,192 枚）で、毎日更新されます。API キーもデータベースもレート制限も不要です。サーバーは独自のパイプラインから公開されたスナップショットを使用するため、クエリ時にサードパーティ API が稼働している必要はありません。

ツール

ツール	機能
search_cards	名前、色、コスト、レアリティ、タイプ、キーワード、ステータス、セット、カード本文でカードを絞り込み、取得します。response_format="toon"を指定すると、トークンを約 10％削減できます
count_cards	カードオブジェクトを取得せずに、フィルターに一致するカードの枚数を数えます
aggregate_cards	cost（インクカーブ）、rarity、color、set_code、type別に件数を集計します
resolve_card	略称、不完全な名前、スペルミスのあるカード名から、最も近いカードをあいまい検索します
top_traits	全カードを対象に、最もよく使われている特性（Storyborn、Hero、Villain、Ally など）を表示します
validate_deck	フォーマットのルール（カード 60 枚以上、同じカードは最大 4 枚、インクは 2 色以下、デュアルインク要件）に照らしてデッキを確認し、{legal, total_cards, inks, violations}を返します
deck_stats	インクカーブ、色の割合、インク可能なカード数、タイプの内訳、キーワード数、サブタイプ数、カードごとのキーワードタグを表示します
import_deck	Dreamborn／Pixelborn のデッキリストをカードに変換します。解決できない行には、あいまい検索の候補を提示します
export_deck	デッキを Dreamborn／Pixelborn 互換のテキストリストに変換します
server_status	起動時のメタデータ（カード数、設定）を表示します

インストール

uvx（推奨 — クローンも Docker も不要）

uvx lorcana-cards-mcp

Claude Desktop／claude_desktop_config.json：

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

Claude CLI：

claude mcp add --scope user -- lorcana uvx lorcana-cards-mcp

pip／pipx

pipx install lorcana-cards-mcp   # then run: lorcana-cards-mcp

Docker

サーバーはGHCRとMCP Registryにも公開されています。

docker run --rm -i ghcr.io/danielenricocahall/lorcana-mcp:latest

{
  "mcpServers": {
    "lorcana": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/danielenricocahall/lorcana-mcp:latest"]
    }
  }
}

コンテナを再起動してもカードキャッシュを保持するには、ボリュームをマウントします。

docker run --rm -i \
  -e LORCANA_CACHE_PATH=/data/cards.json \
  -e LORCANA_SKIP_IF_DB_EXISTS=true \
  -v lorcana_mcp_data:/data \
  ghcr.io/danielenricocahall/lorcana-mcp:latest

クローンから

uv run python main.py

docker build -t lorcana-mcp:latest .
docker run --rm -i lorcana-mcp:latest

# or via compose
docker compose build
docker compose run --rm -T lorcana-mcp

ポートは公開されません。MCP 通信は stdio 経由で行われます。

質問の例

MCP クライアントに接続したら、次のような自然言語で質問できます。

カードの検索

• 「Moana という名前のカードをすべて表示して」
• 「Maui - Hero to All のカード効果を教えて」
• 「アンバーのレジェンダリーカードをすべて検索して」

デッキ構築

• 「筋力が 3 以上のルビーのキャラクターで、最もコストが低いカードは？」
• 「コストが 4 以下の、インク可能なサファイアのカードを表示して」
• 「意思力が 5 以上のスティールのキャラクターを検索して」
• 「エメラルドに伝承が 3 のキャラクターはいる？」

キーワードと能力の検索

• 「コストがちょうど 5 の Singer カードは何枚ある？」
• 「最初のセットに Evasive のキャラクターは何体いる？」
• 「Reckless を持つルビーのカードは何枚ある？」
• 「テキストに Ward が含まれるカードをすべて検索して」
• 「アメジストの Shift カードを表示して」

統計と集計

• 「各セットにはカードが何枚ある？」
• 「全カードの色の分布は？」
• 「最もよく使われている特性は？」
• 「インクカーブを表示して。各コストのカードは何枚ある？」
• 「インク可能なレジェンダリーカードは何枚ある？」

複数条件での検索

• 「伝承が 3 以上のアンバーのキャラクターは何体いる？」
• 「スティールで、コストが低く（2～3）、筋力が高い（4 以上）キャラクターを検索して」
• 「セット 1 で、Evasive を持ち、コストが 4 未満のカードは何枚ある？」

**注：**Evasive、Bodyguard、Shift などのキーワードそのものを検索する場合は、keywordパラメーターを使用してください。構造化された能力リストを対象に絞り込むため、部分文字列検索よりも信頼性が高くなります。Singer 5やResist +2のように値を指定して検索する場合は、body_textを使用してください（キーワードの値は能力リストではなく、カードの全文に含まれています）。

MCP プロンプト

• build_deck(colors, playstyle="balanced") — 指定された色とプレイスタイル（aggressive / control / lore-race / balanced）に応じて、合法なLorcanaデッキ（60枚以上、インクは2色まで、各カード最大4枚）を組み立てる手順をモデルに案内します。上記の検索／集計ツールと、サーバーの指示に含まれるルールを使用します。

カードデータと起動時の動作

起動時、サーバーは https://danielenricocahall.github.io/lorcana-mcp/allCards.jsonからカードのJSONリストを取得します。スナップショットは毎日 data_pipeline/fetch_cards.pyによって更新されます。このスクリプトはLorcast APIからデータを取得し、各カードを内部スキーマに正規化して、gh-pagesブランチにリストを公開します。この中間レイヤーにより、稼働中のサーバーはLorcastの稼働状況やレート制限の影響を受けません。実行時にLorcastへ直接アクセスすることはありません。

カードは、すばやくフィルタリングできるようPythonリストとしてメモリに保持されます。データセットには2,506種類のカードがあり、それぞれに別セット、番号、レアリティを含むprintings配列があります（合計3,192件の印刷）。印刷情報をカードごとに1行にまとめることで、「Elsa」を検索すると、プロモ版の再録ごとに重複することなく、異なるElsaがそれぞれ1回だけ返されます。ローカルJSONファイルのキャッシュ（LORCANA_CACHE_PATH、既定値はcards.json）を使うと、2回目以降の起動時にサーバーはネットワークからの取得を省略できます。

設定

• LORCANA_API（既定値：https://danielenricocahall.github.io/lorcana-mcp/allCards.json）
• LORCANA_CACHE_PATH（既定値：cards.json） — 取得したカードをキャッシュするローカルファイル
• LORCANA_HTTP_TIMEOUT_SECONDS（既定値：60）
• LORCANA_REFRESH_ON_STARTUP（既定値：false） — trueにすると、毎回データを取得して保存領域を再構築します
• LORCANA_SKIP_IF_DB_EXISTS（既定値：true） — falseにすると、キャッシュにデータがある場合でもデータを取得して再構築します

TOONレスポンス形式

search_cardsはresponse_format引数を受け取ります。

• "json"（既定値） — 以前のバージョンと変わらないカードオブジェクトのリストです。
• "toon" — toonsのRustベースのライブラリ（公式コミュニティ参照実装）でエンコードされたTOON文字列です。列見出しの行が1行あり、その後にカードごとの行が続きます。

例（search_cards(name="elsa", limit=2, response_format="toon")）：

cards[2]:
  - id: crd_01c4835a62df4960bb973aeff81f2bb2
    name: Elsa
    version: Ice Maker
    full_name: Elsa - Ice Maker
    cost: 7
    ...
    printings[3]{set_code,set_name,number,rarity}:
      "7",Archazia's Island,69,Super Rare
      C2,Lorcana Challenge Year 3,2,Promo
      C2,Lorcana Challenge Year 3,6,Promo
  - id: crd_04bca46a8e2d4e9ba0fbdbfc6c99e51e
    name: Elsa
    ...

カードの形状には違いがあり、たとえばアクションやアイテムには筋力／意志力／伝承の項目がありません。そのため、外側のcards[2]:は単一の表形式ではなく、YAML形式のカードごとのブロックにフォールバックします。内側のprintings[N]{...}:ブロックは、すべての印刷情報が同じ4つのフィールドを持つため、完全な表形式です。

ベンチマーク

実データの2,506枚のカードを対象に、benchmarks/bench_toon.pyで測定しました。Claudeのトークナイザーの代用として使用されるtiktokenのcl100k_baseでトークン化しています。

query	rows	JSON tokens	TOON tokens	Δ
color="amber", limit=200	200	44,101	39,680	−10.0%
color="ruby", limit=50	50	10,522	9,519	−9.5%
card_type="action", limit=50 (sparse cols)	50	10,154	9,250	−8.9%
body_text="when", limit=50 (long full_text)	50	11,602	10,391	−10.4%
name="elsa", limit=20	14	3,488	2,940	−15.7%
total		79,867	71,780	−10.1%

注：TOONによる削減率は、印刷情報を統合する前と比べて小さくなっています（PR-#29以前は、同じクエリで約50%削減されていました）。この差はネストされたprintings配列の構造によるものです。TOONの列指向エンコードは最上位のフィールドでは効果を発揮しますが、各印刷情報のエントリー内ではJSON形式のエンコードにフォールバックするため、配列によって相対的な削減率が薄まります。ただし、印刷情報を統合する前の同等の行数と比べると、絶対的なトークン数は依然として大幅に減少しています。各カードが、1〜3個の完全な行ではなく、少数の印刷情報を持つ1行として表されるためです。

PYTHONPATH=. uv run python benchmarks/bench_toon.pyで再現できます（cards.jsonキャッシュにデータが格納されている必要があります）。

免責事項

これは個人的な非公式のファンプロジェクトおよびエンジニアリングプロジェクトです。Disney、Ravensburger、またはDisney Lorcana TCGチームとは提携しておらず、これらの企業・団体から承認、後援、レビューを受けていません。Ravensburgerの Disney Lorcana TCGコミュニティコード に従い、公開されているコミュニティデータソースのみを使用して構築・配布しています。Disney Lorcana TCGに関するすべての名称、カードのテキスト、商標、および関連する知的財産は、DisneyおよびRavensburgerに帰属します。このプロジェクトは非営利であり、私個人の見解のみを反映するもので、勤務先の見解を示すものではありません。

---

_{MCP Registryの所有権確認 — レジストリは、このプロジェクトがサーバー名を所有していることを確認するため、公開済みのパッケージ説明からこの行を読み取ります。}

mcp-name: io.github.danielenricocahall/lorcana-mcp