# scryfall-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
[Scryfall](https://scryfall.com/docs/api) Magic: The Gathering API as tools for LLM clients
(Claude Desktop, Claude Code, etc.).

No API key is required — Scryfall is a public API. The server sends a descriptive
`User-Agent`, requests JSON, and throttles itself to ~10 requests/second per Scryfall's
guidelines.

## Tools

**Card search & lookup**
- `search_cards` — full-text search using [Scryfall query syntax](https://scryfall.com/docs/syntax) (pagination, sort, unique modes)
- `get_card_named` — exact or fuzzy name lookup, optional set
- `get_random_card` — a random card, optionally constrained by a query
- `autocomplete_card_names` — name completions for a partial input
- `get_card_by_id` — lookup by Scryfall UUID
- `get_card_by_set_number` — lookup by set code + collector number (+ optional language)
- `get_card_collection` — batch lookup of up to 75 cards by identifier

**Images & prices**
- `get_card_images` — image URIs (small/normal/large/png/art_crop/border_crop), handles double-faced cards
- `get_card_prices` — market prices (USD/foil/EUR/tix) and purchase links
- `get_card_printings` — every printing of a card with per-printing set, rarity, prices, and art

**Sets & rulings**
- `list_sets` — all sets (compact summary)
- `get_set` — a set by code, Scryfall ID, or TCGplayer group ID
- `get_card_rulings` — official rulings by card ID or set + collector number

**Symbology & catalogs**
- `list_symbology` — all card symbols with metadata
- `parse_mana_cost` — parse a mana cost string into canonical form
- `get_catalog` — canonical value lists (creature types, keyword abilities, card names, …)

**Bulk data**
- `list_bulk_data` — list downloadable full-dataset files (returns download URIs)
- `get_bulk_data` — metadata for one bulk file by type or ID

> Card-heavy responses are summarized to the most useful fields to keep output compact.
> Single-card lookups accept `full: true` to return the complete Scryfall object.
> Bulk-data tools return download URIs only — fetch the (often hundreds of MB) files directly.

## Install & build

```bash
npm install
npm run build
```

## Configure a client

Point your MCP client at the built entry. For **Claude Desktop**
(`claude_desktop_config.json`) or **Claude Code** (`.mcp.json`):

```json
{
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/Users/ronald/Desktop/projects/scryfall-mcp/dist/index.js"]
    }
  }
}
```

Or add it to Claude Code from the CLI:

```bash
claude mcp add scryfall -- node /Users/ronald/Desktop/projects/scryfall-mcp/dist/index.js
```

## Development

```bash
npm run dev        # tsx watch mode
npm run typecheck  # tsc --noEmit
```

## License

MIT