Scryfall MCP Server

A comprehensive Model Context Protocol (MCP) server that integrates with the Scryfall API to provide Magic: The Gathering card data and functionality to AI assistants like Claude.

Features

🔧 MCP Tools

search_cards: Search for cards using Scryfall's powerful search syntax
get_card: Get detailed information about specific cards
get_card_prices: Retrieve current price data for cards
random_card: Get random cards with optional filters
search_sets: Search and filter Magic sets

📚 MCP Resources

card-database://bulk: Complete Scryfall bulk card database with daily updates
set-database://all: All Magic sets with metadata and icons

💡 MCP Prompts

analyze_card: Generate comprehensive card analysis including competitive viability, synergies, and meta positioning
build_deck: Create deck building guides centered around specific cards

⚡ Performance Features

Rate Limiting: Respects Scryfall's API limits with 75ms minimum intervals
Intelligent Caching: Reduces API calls by >70% with configurable TTL
Error Handling: Graceful handling of all API error conditions
Circuit Breaker: Prevents cascading failures during API outages

Installation

Prerequisites

Node.js 18+
npm or yarn

Setup

Clone the repository
git clone https://github.com/bmurdock/scryfall-mcp.git cd scryfall-mcp
Install dependencies
npm install
Configure environment (optional)
cp .env.example .env # Edit .env with your preferences
Build the project
npm run build

Usage

Development Mode

npm run dev

Production Mode

npm start

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

MCP Inspector

npm run inspector

Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Replace /absolute/path/to/scryfall-mcp with the actual path to your installation.

Tool Usage Examples

Search Cards

// Basic search
{
  "query": "lightning bolt"
}

// Advanced search with Scryfall syntax
{
  "query": "c:red type:instant cmc:1",
  "limit": 10,
  "format": "json"
}

// Format-specific search
{
  "query": "legal:modern type:creature power>=4",
  "order": "cmc"
}

Get Card Details

// By name
{
  "identifier": "Lightning Bolt"
}

// By set and collector number
{
  "identifier": "dom/123"
}

// By Scryfall ID
{
  "identifier": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a"
}

// With specific set
{
  "identifier": "Lightning Bolt",
  "set": "m21"
}

Get Card Prices

{
  "card_id": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a",
  "currency": "usd"
}

Random Card

// Completely random
{}

// Filtered random card
{
  "query": "type:creature",
  "format": "modern"
}

Search Sets

// All sets
{}

// Filter by type and date
{
  "type": "expansion",
  "released_after": "2020-01-01"
}

Scryfall Search Syntax

The server supports Scryfall's full search syntax:

Basic Operators

c:red - Color
type:creature - Type line
set:dom - Set code
cmc:3 - Converted mana cost
power>=4 - Power/toughness comparisons
legal:modern - Format legality

Advanced Operators

is:commander - Card properties
year:2023 - Release year
rarity:mythic - Rarity
artist:"john avon" - Artist name
flavor:"text" - Flavor text search

Boolean Logic

red OR blue - Either condition
creature AND red - Both conditions
NOT black - Exclude condition
(red OR blue) type:instant - Grouping

Error Handling

The server provides detailed error messages for common issues:

404: Card/resource not found
422: Invalid search syntax
429: Rate limit exceeded (automatic retry)
Validation errors: Parameter validation failures

Performance Monitoring

Cache Statistics

// Get cache performance
server.getCacheStats()

Rate Limiter Status

// Check rate limiting status
server.getRateLimiterStatus()

Health Check

// Overall system health
server.healthCheck()

Configuration

Environment Variables

SCRYFALL_USER_AGENT=ScryfallMCPServer/1.0
CACHE_TTL_HOURS=24
RATE_LIMIT_MS=75
LOG_LEVEL=info
NODE_ENV=development

Cache Durations

Card Search: 30 minutes
Card Details: 24 hours
Card Prices: 6 hours
Set Data: 1 week
Bulk Data: 24 hours

Troubleshooting

Common Issues

"Rate limit exceeded"

The server automatically handles rate limiting
Wait a moment and try again
Check if you're making too many concurrent requests

"Network error: Unexpected token" or gzip-related errors

This was fixed in v1.0.2 by disabling gzip compression
Make sure you're using the latest build: npm run build
Restart Claude Desktop after rebuilding
The server now requests uncompressed responses to avoid parsing issues

"Card not found"

Verify card name spelling
Try using set code + collector number format
Check if the card exists in Scryfall

"Invalid search syntax"

Review Scryfall search syntax documentation
Check for unmatched parentheses
Avoid starting queries with boolean operators

Claude Desktop integration not working

Verify the absolute path in configuration
Ensure the server builds successfully
Check Claude Desktop logs for errors

Debug Mode

LOG_LEVEL=debug npm run dev

Clear Cache

# Programmatically
server.clearCaches()

# Or restart the server

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Development Guidelines

Follow TypeScript best practices
Maintain >80% test coverage
Use conventional commit messages
Update documentation for new features

API Rate Limiting & Compliance

This server fully complies with Scryfall's API guidelines:

Rate Limiting: 100ms minimum between requests (10 requests/second max)
Required Headers: Proper User-Agent and Accept headers
Caching: 24+ hour caching for card data, 6 hours for prices
Bulk Data: Uses daily bulk downloads that don't count against limits
Error Handling: Respects 429 responses with exponential backoff
Circuit Breaker: Prevents overloading during API issues

See SCRYFALL_COMPLIANCE.md for complete compliance details.

License

MIT License - see LICENSE file for details.

Acknowledgments

Scryfall for providing the excellent Magic: The Gathering API
Model Context Protocol for the MCP specification
The Magic: The Gathering community for inspiration and feedback

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A comprehensive Model Context Protocol server that integrates with the Scryfall API to provide Magic: The Gathering card data to AI assistants like Claude.

Related MCP Servers

Scryfall MCP Server
cryppadotta
-
security
F
license
-
quality
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.
Last updated -
7
5
1
JavaScript
API Tester MCP Server
Vikrant-Khedkar
-
security
F
license
-
quality
A Model Context Protocol server that allows Claude to make API requests on your behalf, providing tools for testing various APIs including HTTP requests and OpenAI integrations without sharing your API keys in the chat.
Last updated -
Python
MTG Deck Manager MCP Servers
artillect
-
security
F
license
-
quality
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.
Last updated -
Python
Atlassian Confluence MCP Server
aashari
A
security
F
license
A
quality
A Model Context Protocol server that enables AI assistants like Claude to access and search Atlassian Confluence content, allowing integration with your organization's knowledge base.
Last updated -
5
319
8
TypeScript

View all related MCP servers