Scryfall MCP

🚀 Scryfall MCP Server

This is a comprehensive Model Context Protocol (MCP) server that integrates with the Scryfall API. It provides 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

1. Clone the repository

   git clone https://github.com/bmurdock/scryfall-mcp.git
   cd scryfall-mcp
   

2. Install dependencies

   npm install
   

3. Configure environment (optional)

   cp .env.example .env
   # Edit .env with your preferences
   

4. 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

💻 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"
}

📚 Documentation

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

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.

🔧 Technical Details

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

This project is under the MIT License. See the 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.