Lorcana MCP Server

An MCP server for searching and aggregating Disney Lorcana cards.

Startup behavior

On startup, the server fetches a JSON list of cards from https://danielenricocahall.github.io/lorcana-mcp/allCards.json. The snapshot is refreshed daily by data_pipeline/fetch_cards.py, which pulls from the Lorcast API, normalizes each card into our internal schema, and publishes the list to the gh-pages branch. The middle layer insulates running containers from Lorcast's availability and rate limits — the runtime never calls Lorcast directly.

Cards are kept in-memory as a Python list for fast filtering. With ~2,270 unique cards (each carrying a printings array for its alternate sets/rarities) this is lightweight and requires no external database. A local JSON file cache (LORCANA_CACHE_PATH, default cards.json) lets the server skip the network fetch on subsequent startups.

Startup data loading is controlled by:

• LORCANA_REFRESH_ON_STARTUP:
  • true: always fetch from API and repopulate storage
  • false: use existing cache if available
• LORCANA_SKIP_IF_DB_EXISTS:
  • true (default): skip API fetch if the cache file already contains cards
  • false: fetch and repopulate

Quick start (no clone required)

The server is published to GHCR and the MCP Registry. Pull and run it directly:

docker pull ghcr.io/danielenricocahall/lorcana-mcp:latest

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

To persist the card cache across container restarts, mount a volume:

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

Run locally (stdio MCP)

uv run python main.py

Docker

Build image

docker build -t lorcana-mcp:latest .

Run as stdio MCP server

docker run --rm -i lorcana-mcp:latest

Docker Compose

Start with compose

docker compose build
docker compose run --rm -T lorcana-mcp

Notes:

• No port is exposed; MCP communication is over stdio.
• Use a volume to persist the JSON cache across restarts.

Config

• LORCANA_API (default: https://danielenricocahall.github.io/lorcana-mcp/allCards.json)
• LORCANA_CACHE_PATH (default: cards.json) — local file for caching fetched cards
• LORCANA_HTTP_TIMEOUT_SECONDS (default: 60)
• LORCANA_REFRESH_ON_STARTUP (false default)
• LORCANA_SKIP_IF_DB_EXISTS (true default)

MCP client setup examples

Local process (Claude Desktop-style)

{
  "mcpServers": {
    "lorcana": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/lorcana-mcp/main.py"]
    }
  }
}

Published image — GHCR (Claude Desktop-style, no clone required)

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

Docker process (Claude Desktop-style, locally built)

{
  "mcpServers": {
    "lorcana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "lorcana-mcp:latest"
      ]
    }
  }
}

Docker Compose process (Claude Desktop-style)

{
  "mcpServers": {
    "lorcana": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "-T", "lorcana-mcp"]
    }
  }
}

Via the Claude CLI — published image (global, no clone required)

claude mcp add --scope user \
  -- lorcana docker run --rm -i \
  ghcr.io/danielenricocahall/lorcana-mcp:latest

Via the Claude CLI — l

... View full README on GitHub