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

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

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:

Log Aggregation: ELK Stack (Elasticsearch, Logstash, Kibana)
Metrics: Grafana with Prometheus
Error Tracking: Sentry with structured error context
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

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

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.