# ShuffleReady

> ShuffleReady (https://shuffleready.com) is a Magic: The Gathering deck builder and format checker. Its public API says whether a deck is legal in a format and why not, today or on any past date, using each format's dated rules and ban lists (Commander back to 2002).

No API key is needed. Limits: 30 requests per minute per IP, 10 per minute for decks given as a url. CORS is open, without credentials.

## MCP server

A remote MCP server (Streamable HTTP, no auth) at `https://shuffleready.com/mcp`, for Claude, ChatGPT and other agents: add it as a custom connector. Its read-only tools are `check_deck_legality`, `list_formats`, `format_rules_on_date` (a format's checks and ban lists on a date) and `card_legality` (one card in each official format). Calls count against the same limits.

## API

- [API docs](https://shuffleready.com/api): the same, for people, with examples
- [OpenAPI description](https://shuffleready.com/api/v1/openapi.json): every endpoint and field
- `POST https://shuffleready.com/api/v1/legality`: JSON body `{ "deck": string, "formats": [slug or id, ...], "asOf"?: "YYYY-MM-DD", "allowNewCards"?: boolean }`
- `GET https://shuffleready.com/api/v1/legality?deck=...&format=...&format=...&asOf=...&allowNewCards=true`: the same, for short decks
- `GET https://shuffleready.com/api/v1/formats`: the format slugs, names, ids and earliest dates

`deck` is a deck list, one card per line (`1 Sol Ring`, `4x Lightning Bolt`), with lines like `Commander` starting a category, at most 250 lines. Or a link to a deck on Moxfield, Archidekt and similar sites. Name 1 to 5 formats.

`asOf` checks the deck as it would have been on that date: `YYYY-MM-DD`, `YYYY-MM` (the month's last day) or `YYYY` (December 31). The format's rules and ban lists in effect then apply, and cards printed after it fail with `NOT_YET_PRINTED`. A date before a format's first rules gives that format `error.code: FORMAT_NOT_YET_PUBLISHED` with its `firstDate`.

`allowNewCards: true` (needs `asOf`) keeps that date's rules and ban lists but allows cards printed after it: old rules, new cards. Those cards don't fail; they're listed in `deck.printedAfterAsOf` with the date each was first printed. A format's own release rules (a card pool, say) still apply.

Each result has `legal` (true/false), `status` (`LEGAL`, `FAILED_CHECKS`, or `INVALID_CARDS` when a name matched no card), `errors` (each failed check with the cards and the reason for each) and `tier` (the Commander bracket, for Commander). Names that matched no card are in `deck.unresolved` with suggestions; the other cards are still checked.

## Examples

Is this deck legal in Commander today?

```
curl -s https://shuffleready.com/api/v1/legality -H 'content-type: application/json' \
  -d '{"deck":"Commander\n1 Kenrith, the Returned King\nDeck\n1 Sol Ring\n1 Mana Crypt","formats":["commander"]}'
```

Was it legal in EDH at the end of 2007?

```
curl -s https://shuffleready.com/api/v1/legality -H 'content-type: application/json' \
  -d '{"deck":"1 Sol Ring\n1 Jeweled Lotus","formats":["edh"],"asOf":"2007"}'
```

Would it pass the 2007 ban list, with today's cards allowed?

```
curl -s https://shuffleready.com/api/v1/legality -H 'content-type: application/json' \
  -d '{"deck":"1 Sol Ring\n1 Jeweled Lotus","formats":["edh"],"asOf":"2007","allowNewCards":true}'
```

A short deck by GET, in two formats:

```
curl -s 'https://shuffleready.com/api/v1/legality?deck=4%20Lightning%20Bolt%0A4%20Brainstorm&format=vintage&format=commander'
```

## Formats

- `commander` (also: edh, elder-dragon-highlander): Commander, rules from 2002-10-01
- `commander-bracket-1-exhibition`: Commander Bracket 1: Exhibition, rules from 2025-02-11
- `commander-bracket-2-core`: Commander Bracket 2: Core, rules from 2025-02-11
- `commander-bracket-3-upgraded`: Commander Bracket 3: Upgraded, rules from 2025-02-11
- `commander-bracket-4-optimized`: Commander Bracket 4: Optimized, rules from 2025-02-11
- `commander-bracket-5-cedh` (also: cedh): Commander Bracket 5: cEDH, rules from 2025-02-11
- `legacy` (also: type-1-5): Legacy, rules from 2004-09-01
- `modern`: Modern, rules from 2011-08-01
- `oathbreaker`: Oathbreaker, rules from 2019-05-01
- `old-school-93-94`: Old School 93/94, rules from 2019-09-07
- `pauper-commander` (also: pdh, pauper-edh): Pauper Commander, rules from 2019-06-01
- `pioneer`: Pioneer, rules from 2019-10-01
- `premodern`: Premodern, rules from 2023-07-01
- `standard-brawl`: Standard Brawl, rules from 2018-05-10
- `tiny-leaders-reborn` (also: tiny-leaders): Tiny Leaders: Reborn, rules from 2026-10-05
- `vintage` (also: type-1): Vintage, rules from 1994-01-01

Any other public format on ShuffleReady can be named by its numeric id (the number in its page's url, https://shuffleready.com/format/1/<id>).