Skip to main content
Glama
JoeMoCode

Scryfall MCP Server

by JoeMoCode
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Scryfall MCP Server

A Model Context Protocol (MCP) server that brings Magic: The Gathering card data directly into Claude Desktop. Ask Claude about any Magic card, and it will provide detailed information from Scryfall's comprehensive database.

What Can It Do?

  • Search for Cards - Find cards by name, type, color, mana cost, or any game characteristic you can think of

  • Get Card Details - View complete card information including prices, format legalities, and high-quality images

  • Explore Sets - Learn about Magic sets, their release dates, and what cards they contain

  • Random Cards - Discover random cards for deck inspiration or just for fun

  • Smart Caching - Previously viewed cards load instantly from a local cache

  • Resource Browser - Access your recently viewed cards through Claude's resource system

Related MCP server: MTG Deck Manager MCP Servers

Installation

Prerequisites

You'll need Node.js and npm installed on your computer. npm is a tool that helps install and manage the software this server needs to run.

To install Node.js and npm:

  • On Mac:

    • Download from nodejs.org and run the installer, or

    • If you have Homebrew: brew install node

  • On Windows:

To verify it's installed, open a terminal and type: npm --version

Installation Steps

  1. Clone or download this repository

  2. Install dependencies:

    npm install

  3. Build the server:

    npm run build

Configuration

For Claude Desktop

  1. Locate your Claude Desktop config file:

    • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the server configuration:

    {
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"]
    }
  }
}

    Replace /absolute/path/to/your/project with the actual path to this project directory.

  3. Restart Claude Desktop

How to Use

Once you've installed and configured the server, you can simply ask Claude about Magic cards in natural language. Here are some examples:

Searching for Cards

  • "Search for Lightning Bolt"

  • "Find all red creatures with power 4 or greater"

  • "Show me cards with 'draw a card' in their text"

  • "Find blue instants that cost 2 mana"

Getting Card Information

  • "Tell me about Black Lotus"

  • "What are the format legalities for Sol Ring?"

  • "Show me the current price of Jace, the Mind Sculptor"

  • "Get details for Ragavan, Nimble Pilferer"

Exploring Sets

  • "What's in the Dominaria United set?"

  • "Tell me about set code MOM"

  • "Show me information about the latest set"

Random Discovery

  • "Show me a random card"

  • "Give me 3 random creatures"

  • "Surprise me with 5 random cards"

Accessing Recently Viewed Cards

Cards you've already looked up are cached locally and appear in Claude's resource browser, making them quick to access again without additional searches.

Technical Details

Available Tools

The server provides these tools that Claude can use:

search_cards - Search for cards using Scryfall's powerful search syntax

  • Supports searching by name, type, color, mana cost, card text, set, rarity, and more

  • Returns up to 10 results by default (configurable)

get_card_details - Get complete information about a specific card

  • Includes prices, legalities, images, and all card attributes

  • Uses smart caching to speed up repeated lookups

get_set_info - Get information about a Magic set

  • Requires the set code (like "dmu" for Dominaria United or "mom" for March of the Machine)

get_random_card - Get random cards

  • Can request multiple random cards at once

  • Great for deck inspiration or exploring the game

Resources Feature

The server implements MCP resources, which means:

  • Cards you look up are cached locally for 1 hour

  • Recently viewed cards appear in Claude's resource browser

  • Cached cards load instantly without making new API requests

  • The cache automatically cleans up old entries

Development

Running in Development Mode

npm run dev

Building

npm run build

Project Structure

├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Node.js dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Performance & Limits

Smart Caching

To improve speed and reduce unnecessary API calls, this server caches card information:

  • Cached cards load instantly

  • Cache expires after 1 hour

  • Up to 100 cards stored in memory at once

Scryfall API Rate Limits

This server uses Scryfall's free API, which allows:

  • Up to 100 requests per second

  • No API key required

The server automatically handles errors and rate limits gracefully.

Troubleshooting

The server isn't showing up in Claude Desktop

  1. Check your configuration file - Make sure the path is correct and the JSON syntax is valid

    • On Mac: cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

    • On Windows: Open the file in Notepad and verify it looks correct

  2. Verify the path is absolute - The path must be complete (like /Users/yourname/projects/ScryfallMCP/dist/index.js), not relative (like ./dist/index.js)

  3. Make sure it built successfully:

    npm run build

  4. Restart Claude Desktop completely - Quit the app entirely and reopen it

Claude says "Unknown tool" or the tools don't work

  • This usually means Claude Desktop didn't reload the configuration

  • Try restarting Claude Desktop again

  • Check that the dist/index.js file exists after running npm run build

API or connection errors

  1. Check your internet connection - The server needs to reach Scryfall's API

  2. Visit https://scryfall.com to make sure their service is up

  3. Look at the console output when running npm run dev to see detailed error messages

Build or installation problems

  • "npm: command not found" - You need to install Node.js and npm (see Prerequisites above)

  • Build failures - Try deleting the node_modules folder and running npm install again

  • Permission errors - Make sure you have permission to read and execute files in the project folder

Contributing

Want to improve this server? Contributions are welcome!

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Test thoroughly

  5. Submit a pull request with a clear description of what you've added and why

License

This project is licensed under the MIT License.

Acknowledgments

Available Tools

4 tools
get_card_detailsA

Get detailed information about a specific card by exact name

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesExact card name

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description only states it returns 'detailed information' but does not disclose the structure of output, error handling, or potential limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that communicates the core functionality without any unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and single parameter, the description covers the basic purpose but lacks details on return values or error conditions, leaving some gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The parameter 'name' is fully described in the schema (100% coverage); the description adds the qualifier 'exact' but does not provide additional meaning beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves detailed information about a specific card by exact name, differentiating it from siblings like search_cards which may return multiple results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when the exact card name is known, but lacks explicit guidance on when to use alternatives like search_cards for partial matches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_random_cardA

Get one or more random Magic: The Gathering cards

ParametersJSON Schema
NameRequiredDescriptionDefault
countNoNumber of random cards to get (default: 1)

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only mentions 'random' without explaining the nature of randomness, rate limits, or any side effects. This is minimal for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extraneous information. It is front-loaded and efficiently conveys the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For this simple tool (one parameter, no output schema), the description provides sufficient context to understand its function. It could optionally mention that it returns card objects, but the absence is not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the 'count' parameter is fully documented). The description adds 'one or more', which aligns with the schema but does not provide significant new meaning beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the object 'random Magic: The Gathering cards', and the scope 'one or more'. It effectively differentiates from sibling tools like 'get_card_details' (for specific cards) and 'search_cards' (for filtered searches).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for random card generation but does not explicitly state when to use this tool versus alternatives. No exclusions or specific context cues are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_set_infoC

Get information about a Magic: The Gathering set

ParametersJSON Schema
NameRequiredDescriptionDefault
set_codeYesThree or four letter set code (e.g., "dmu", "neo")

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description should disclose behavioral traits like read-only, error handling, or authentication needs. It only says 'Get information' with no further details, leaving the agent unaware of potential side effects or constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is front-loaded with key action, though it may be under-specified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema and low complexity, the description should at least hint at the return value (e.g., set metadata). It is incomplete for an agent to understand what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with description and examples. The description adds no extra meaning beyond what the schema provides, so baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets information about a Magic: The Gathering set, using a specific verb and resource. It distinguishes from sibling tools which focus on cards, but could be more specific about what information is included.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no conditions or prerequisites. The description only states the basic function without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_cardsA

Search for Magic: The Gathering cards by name, type, or other criteria

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query using Scryfall syntax. Supported prefixes: c:/color: (card color), id:/identity: (color identity), t:/type: (card/sub/supertype), o:/oracle: (card text), fo:/fulloracle: (full oracle text), keyword:/kw: (keyword abilities), m:/mana: (mana symbols), mv:/manavalue: (converted mana cost), power:, toughness:, loyalty:, devotion:, is: (card characteristics), f:/format: (format legality), e:/s:/set: (set code), r:/rarity:, a:/artist:, year:, game: (paper/arena/mtgo), usd: (USD price), eur: (EUR price), tix: (MTGO ticket price). Operators: >, <, =, >=, <=, !=. Use OR for alternatives, - for negation, parentheses for grouping, quotes for exact phrases, ! for exact names.
limitNoMaximum number of results (default: 10)

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must carry the burden of behavioral transparency. It only states the basic function and mentions Scryfall syntax, but does not disclose whether the operation is read-only, any rate limits, pagination, or side effects. This is minimal disclosure for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and front-loads the purpose. Every word is necessary; no fluff. Excellent structure for a summary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only two parameters with full schema descriptions and no output schema, the description covers the basic purpose. However, it lacks information about return format or pagination. It is minimally complete but leaves some context gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the parameter descriptions in the schema are very detailed (e.g., query lists many Scryfall prefixes and operators). The tool description adds only a brief summary ('by name, type, or other criteria') which does not significantly enhance understanding beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search for Magic: The Gathering cards by name, type, or other criteria'. The verb 'Search' and resource 'Magic: The Gathering cards' are specific. It distinguishes from siblings (get_card_details, get_random_card, get_set_info) by implying general search capability.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates the tool is for searching by various criteria, but does not explicitly state when to use this tool versus siblings (e.g., use get_card_details for a specific card, get_random_card for random). No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv1.0.0
    • First observedget_card_details
    • First observedget_random_card
    • First observedget_set_info
    • First observedsearch_cards
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: get_card_details for exact card lookup, get_random_card for random cards, get_set_info for set metadata, and search_cards for flexible queries. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (get_card_details, get_random_card, get_set_info, search_cards). The use of 'get' and 'search' as verbs is uniform and predictable.

Tool Count5/5

With 4 tools, the server is well-scoped for a card database. The tools cover the primary needs: searching, getting details, random retrieval, and set information. This is an effective small set without bloat.

Completeness4/5

The core functionalities are covered: search, detail, random, and set info. Minor gaps like fetching by ID, rulings, or card art exist but do not break typical workflows. Agents can work around these.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Scryfall MCP Server

    cryppadotta
    A
    license
    A
    quality
    D
    maintenance
    Enables interaction with the Scryfall API, allowing users to search for Magic: The Gathering card details, retrieve card rulings, and access pricing information using the Model Context Protocol.
    7
    45
    34
    MIT

  • MTG Deck Manager MCP Servers

    artillect
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables Magic: The Gathering players to manage decks and access card information through Claude, supporting gameplay actions like drawing cards and mulligans while providing Scryfall API integration for card lookups.
    15
    -

  • MTG Card Lookup MCP Server

    jabelk
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables fuzzy lookup of Magic: The Gathering cards by name using the Scryfall API, returning card details including type, oracle text, mana value, and images.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/JoeMoCode/Scryfall-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server