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

Enhanced Search Tools

• build_scryfall_query: Convert natural language requests into optimized Scryfall search queries

  • Input: Natural language description, format preferences, optimization strategy

  • Output: Optimized Scryfall query with explanation and alternatives

  • Example: "red creatures under $5 for aggressive decks" → "c:r t:creature usd<=5 pow>=2 cmc<=3"

Core Search 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 100ms 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

🔍 Simple Validation System

• Lightweight Validation: Basic query syntax validation with helpful error messages

• Essential Checks: Balanced parentheses, quotes, and common syntax errors

• Operator Recognition: Validates known Scryfall operators with suggestions for typos

• Performance Optimized: Fast validation with minimal overhead

Related MCP server: API Tester MCP Server

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

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

Natural Language Query Building

Convert natural language to Scryfall syntax:

// Convert natural language to optimized Scryfall query
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "blue counterspells in modern under $20",
    "optimize_for": "precision"
  }
}

Generate budget-friendly queries:

// Budget-focused query generation
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "aggressive red creatures for standard",
    "optimize_for": "budget",
    "price_budget": {
      "max": 5,
      "currency": "usd"
    }
  }
}

Discover interesting cards:

// Discovery-optimized search
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "legendary artifacts that produce mana",
    "format": "commander",
    "optimize_for": "discovery"
  }
}

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
RATE_LIMIT_MS=100
LOG_LEVEL=info
NODE_ENV=development
# Optional timeouts and health/deep checks
SCRYFALL_TIMEOUT_MS=15000
HEALTHCHECK_DEEP=false
# Bound the internal rate limiter queue
RATE_LIMIT_QUEUE_MAX=500

Cache Durations

• Card Search: 30 minutes

• Card Details: 24 hours

• Card Prices: 6 hours

• Set Data: 1 week

• Bulk Data: 24 hours

Logging Configuration

The server uses Pino for high-performance structured logging with comprehensive error tracking and monitoring.

Log Levels

# Available log levels (default: info)
LOG_LEVEL=trace    # Most verbose - all operations
LOG_LEVEL=debug    # Debug information and performance metrics
LOG_LEVEL=info     # General information (default)
LOG_LEVEL=warn     # Warnings and degraded performance
LOG_LEVEL=error    # Errors only
LOG_LEVEL=fatal    # Critical errors only

Development vs Production Logging

Development Mode (NODE_ENV=development):

• Pretty-printed, colorized output

• Human-readable timestamps

• Request ID and tool name highlighting

• Automatic log formatting for readability

Production Mode (NODE_ENV=production):

• JSON-structured logs for machine processing

• Optimized for log aggregation systems

• Minimal overhead for high-performance scenarios

• Compatible with ELK Stack, Grafana, and monitoring tools

Structured Log Format

All logs include structured context for debugging and monitoring:

{
  "level": "info",
  "time": "2025-01-17T19:32:53.123Z",
  "pid": 12345,
  "hostname": "server-01",
  "service": "scryfall-mcp",
  "version": "1.0.0",
  "requestId": "req_1737145973123_abc123def",
  "toolName": "search_cards",
  "operation": "tool_execution",
  "duration": 245,
  "msg": "Tool execution completed"
}

Request Correlation

Every request gets a unique correlation ID for tracking across operations:

• Format: req_{timestamp}_{random}

• Tracks tool executions, API calls, and errors

• Enables end-to-end request tracing

• Automatic cleanup of old correlation data

Error Handling & Monitoring

Error Classification

The server implements comprehensive error handling with structured error classes:

Base Error Types:

• MCPError - Base class with structured logging support

• ToolExecutionError - Tool-specific execution failures

• ResourceError - Resource access failures

• PromptError - Prompt generation failures

Domain-Specific Errors:

• ScryfallAPIError - Scryfall API-related errors

• RateLimitError - Rate limiting and throttling

• ValidationError - Input validation failures

Error Monitoring Features

Automatic Error Tracking:

• Error frequency monitoring by type

• Performance metrics collection

• Request correlation tracking

• Circuit breaker pattern for API failures

Monitoring Data Access:

// Get comprehensive monitoring report
const status = server.getStatus();
console.log(status.monitoring);

// Output includes:
// - Error counts by type
// - Performance metrics (avg response times)
// - Request correlation data
// - Health check status

Health Check Monitoring

Enhanced health checks with detailed service status:

# Health check includes:
# - Cache service status
# - Rate limiter status
# - Scryfall API connectivity
# - Error monitoring metrics
# - Performance statistics

Production Monitoring Setup

Recommended Monitoring Stack:

1. Log Aggregation: ELK Stack (Elasticsearch, Logstash, Kibana)

2. Metrics: Grafana with Prometheus

3. Error Tracking: Sentry with structured error context

4. Alerting: Based on error rates and response times

Key Metrics to Monitor:

• Tool execution success/failure rates

• API response time distributions

• Error type frequencies

• Cache hit/miss ratios

• Rate limiter status

Error Recovery Strategies

Automatic Recovery:

• Exponential backoff for API failures

• Circuit breaker prevents cascading failures

• Intelligent retry logic with jitter

• Graceful degradation during outages

Manual Recovery:

// Reset error monitoring
server.resetRateLimiter();
server.clearCaches();

// Check system health
const health = await server.healthCheck();

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

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass

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

HTTP Behavior & Headers

• The server sends a descriptive User-Agent and Accept: application/json on all Scryfall API calls, per Scryfall guidelines.

• All fetch calls have a configurable timeout via SCRYFALL_TIMEOUT_MS (default 15000 ms). Aborted requests surface with error code timeout in logs.

• Bulk data and icon downloads also include User-Agent; icons set Accept: image/svg+xml.

Search Pagination Notes

• Scryfall’s /cards/search endpoint does not support a custom page size. The limit parameter in tools controls how many results are displayed from each Scryfall page, client-side.

• Pagination metadata (like total pages) is computed using Scryfall’s total_cards and your requested limit for accurate display.