# Scryfall MCP > Scryfall gives you instant access to the entire Magic: The Gathering card database through an open API. Your AI agent can search for cards, fetch official rulings, list all sets, and pull deep data points using over a dozen specialized tools—all without leaving your workflow. ## Overview - **Category:** databases - **Price:** Free - **Tags:** magic-the-gathering, mtg, card-database, trading-card-game, scryfall ## Description **Scryfall MCP Server: Your Deep Dive into Magic: The Gathering Data** You're talking to your agent about *Magic*? This server hooks up your AI client directly to Scryfall's massive card database. You won't waste time jumping between tabs or wrestling with limited APIs; you just ask, and the data shows up structured for your workflow. **Advanced Card Searching and Lookups** Your agent can run complex queries across every card in existence using `search_cards`, letting you filter results by color, cost, type, or specific text. You never need the exact spelling when searching because `get_card_named` handles fuzzy matching for cards by name. If you're just typing a prompt and need suggestions, `autocomplete_cards` pops up possible card names as you go. To get full card details using precise identifiers, you've got several options. You can fetch a card's entire data set if you know its internal Scryfall ID using `get_card_by_id`. If you have the card's MTGO identifier for that specific game version, use `get_card_by_mtgo_id`; or if you only have the Multiverse unique number, `get_card_by_multiverse_id` gets it for you. You can also pinpoint a card using its Arena ID with `get_card_by_arena_id`, or by knowing both the set code and collector number via `get_card_by_set_number`. When you need details on a specific expansion, simply call `get_set_by_code` (like 'alpha') or use the unique Scryfall ID with `get_set_by_id` to pull all that data. **Managing Collections and Bulk Data** Need info on more than one card? You don't gotta run a query for each one. Use `get_cards_collection` to pass in a list of various identifiers—names or IDs—and get them all back in one go. If you need an overview of what data Scryfall tracks, `get_catalog` gives you the full rundown of available API points. To map out game history, `list_sets` provides a complete roster of every official set that’s ever been released into the database. **Official Rules and Set Details** Determining legality is where this server shines. For judge rulings or official oracle text on a card, use `get_rulings_by_id` with the Scryfall ID; alternatively, you can get rules by specifying the set code and collector number using `get_rulings_by_set_number`. The system also lets you retrieve all data for an entire game expansion using `get_set_by_code`, or just fetch its details with `get_set_by_id`. **Utility Tools for Deep Analysis** The server provides several mechanical tools to help your agent structure raw data. To understand what symbols are on cards (like 'Legendary' or 'Artifact'), call `list_symbology`, which returns a complete list of all known symbols. If you're dealing with cost strings, `parse_mana` converts that text into structured data your agent can actually read and process. For downloadable file lists, run `list_bulk_data` to see everything available; then use `get_bulk_data_by_type` to retrieve a specific bulk data file based on its defined type. When you need to know what data is even possible to download in bulk, `list_bulk_data` shows all options. Finally, if your agent needs to check the raw list of available Magic sets before running any searches, it can call `list_sets`. That's everything you need right there. ## Tools ### autocomplete_cards Suggests possible card names as you type them into the agent prompt. ### get_bulk_data_by_type Retrieves a specific bulk data file based on its defined file type. ### get_card_by_arena_id Fetches card details using the unique Arena ID associated with that card. ### get_card_by_id Gets a card's full data set when you provide its Scryfall internal ID. ### get_card_by_mtgo_id Retrieves card details using the specific MTGO identifier for that game version of the card. ### get_card_by_multiverse_id Fetches a card's data when you provide its Multiverse unique ID. ### get_card_by_set_number Gets a card by providing both the set code and the collector number (e.g., Alpha 1). ### get_catalog Provides an overview and catalog of all available Magic data points the API tracks. ### get_cards_collection Retrieves a group of cards by listing multiple identifiers like names or IDs in one call. ### list_bulk_data Lists all available bulk data files, helping you find what data is downloadable. ### list_sets Provides a list of every official Magic set that has been released into the database. ### list_symbology Returns a complete list of all symbols used on cards (e.g., legendary, artifact). ### get_card_named Finds cards using their name, supporting fuzzy matching so you don't need exact spelling. ### parse_mana Converts a string that looks like mana costs into structured data your agent can read. ### get_rulings_by_id Gets official ruling text for a card using its specific Scryfall ID. ### get_rulings_by_set_number Retrieves rulings by specifying the set code and collector number for accuracy. ### search_cards Runs comprehensive searches across all cards, supporting advanced filtering by type, color, and text. ### get_set_by_code Fetches all data for a game expansion when you provide its unique code (e.g., alpha). ### get_set_by_id Retrieves set details using the set's specific Scryfall ID. ## Prompt Examples **Prompt:** ``` Search for all legendary dragons that are red and cost 5 mana or less. ``` **Response:** ``` I found several cards matching your criteria, including 'Lathliss, Dragon Queen' and 'Rith, Liberated Primeval'. Would you like to see the full details for any of these? ``` **Prompt:** ``` Get the card details for 'Sol Ring'. ``` **Response:** ``` Sol Ring is a legendary artifact that costs 1 generic mana. Its ability is '{T}: Add {C}{C}'. It has been printed in many sets, including Alpha and Commander editions. ``` **Prompt:** ``` List all Magic: The Gathering sets released in 2023. ``` **Response:** ``` In 2023, Scryfall records several major releases including 'Phyrexia: All Will Be One' (ONE), 'March of the Machine' (MOM), and 'Wilds of Eldraine' (WOE). ``` ## Capabilities ### Advanced Card Search Run complex queries across the entire card database using specialized syntax (e.g., filtering by color, cost, or type). ### Official Ruling Retrieval Fetch judge rulings and official oracle text for specific cards or sets to resolve game legality issues. ### Targeted Card Lookup Retrieve a card's full details using precise identifiers like its Scryfall ID, Multiverse ID, or MTGO ID. ### Collection Data Management Get bulk data for multiple cards at once by passing a list of various identifiers (names, IDs, etc.). ### Game History Mapping List all existing Magic sets or retrieve details on specific expansions using set codes and names. ## Use Cases ### Verifying Deck Legality for Publishing A game designer is creating a new set and needs to ensure every card interacts correctly. They ask their agent: 'What are the official rulings for Card A interacting with Card B in Set X?' The agent uses `get_rulings_by_set_number`, which returns precise, verifiable text, confirming if the interaction breaks game rules. ### Building a Digital Inventory Tool A collector wants to track their entire physical collection's value and details. They ask: 'Get me all cards with the name 'Lightning Bolt' from sets Alpha, Beta, and Unlimited.' The agent uses `get_cards_collection` to batch-pull data for every instance, structuring it for a database. ### Creating Card Synergy Checkers A player is building a deck and needs to find all legendary creatures that cost 3 mana or less in red. They ask: 'Search for red legendary cards costing three mana.' The agent uses `search_cards` with multiple filters, providing a list of viable options instantly. ### Cross-Reference Data for Development A developer is building an app that needs to display card history. They ask: 'What were the original details for Sol Ring?' The agent uses `get_card_by_mtgo_id` or `get_card_by_multiverse_id` to pull historical data, ensuring their app has accurate source material. ## Benefits - You get structured JSON output for every request. Instead of parsing messy web pages, your agent receives clean, machine-readable data directly from tools like `get_card_by_id` and `search_cards`. - The server handles complex searching using specialized syntax. You can filter cards by type, color, or mana value in one shot with the robust `search_cards` tool—no guessing needed. - You don't need to memorize multiple IDs. The tools allow you to look up data via name (`get_card_named`), specific set codes (`get_set_by_code`), or collection numbers (`get_card_by_set_number`). - Rule checking is instant and accurate. Tools like `get_rulings_by_id` pull the official judge rulings, solving complex interactions that would otherwise require manual cross-referencing. - You can build powerful data pipelines by fetching multiple records at once. Use `get_cards_collection` to analyze entire groups of cards using various identifiers. ## How It Works The bottom line is: Your AI client executes complex database queries using dedicated tools, so you get clean JSON output instead of a webpage. 1. Subscribe to the Scryfall server. Your agent now recognizes its 19 specialized tools. 2. Prompt your AI client with a query (e.g., 'What are the rulings for Black Lotus in Alpha?'). 3. The agent determines it needs `get_rulings_by_set_number`, calls that tool, and receives structured card data back. ## Frequently Asked Questions **How do I search for cards using Scryfall's advanced syntax with `search_cards`?** You include complex filters directly in your prompt. For example, 'Search for red legendary dragons that cost 5 mana or less.' The `search_cards` tool handles the full syntax mapping automatically. **I need rulings for a card. Should I use `get_rulings_by_id` or `get_rulings_by_set_number`?** Use `get_rulings_by_set_number` if you care about the specific set version (e.g., Alpha). Use `get_rulings_by_id` if you just need the general, universal ruling for that card's existence. **What is the best tool to get a card by name?** The `get_card_named` tool handles this. It supports fuzzy matching, meaning you don't have to type the name perfectly; it still finds the right card. **How do I list every available MTG set? Do I need a special tool?** You just use the `list_sets` tool. It queries and returns a complete, current list of all known Magic sets in the database for you to work with. **If I have multiple cards, how do I get them all at once? Which tool should I use?** Use `get_cards_collection`. This tool accepts a list of identifiers—like names or IDs—and fetches the data for the entire group in one go. **If I know a card's Multiverse ID, should I use `get_card_by_multiverse_id` instead of searching?** Yes, using `get_card_by_multiverse_id` is the most direct approach. This tool bypasses general search syntax and pulls the full card record immediately, regardless of its name or set number. **I'm not sure of a card's spelling; how can I check potential names using `autocomplete_cards`?** `autocomplete_cards` quickly generates suggestions as you type. This saves time when the exact name isn't available and helps narrow down the possibilities before running a full search. **I have a mana cost string that I need to validate; should I use `parse_mana`?** You should absolutely use `parse_mana`. This tool isolates mana text, allowing you to programmatically check or interpret the exact resources required by a card without needing to fetch the entire record. **Does the search tool support complex Scryfall syntax like 't:creature c:g cmc=3'?** Yes! The `search_cards` tool accepts any valid Scryfall search query, allowing you to filter by type, color, mana cost, power/toughness, and more. **Can I find a card even if I don't remember the exact spelling of its name?** Absolutely. Use the `get_card_named` tool with the `fuzzy` parameter. Scryfall's engine will suggest the closest match to your input. **How do I get the official rulings for a specific card interaction?** You can use the `get_rulings_by_id` tool. By providing the card's Scryfall ID, the agent will return all official judge rulings and timing notes associated with that card.