Utilizes environment configuration through .env files for server customization.
Hosts the server repository for cloning and contributing through GitHub's platform.
Provides specific configuration instructions for Claude Desktop integration on macOS systems.
Integrates with the Scryfall API to provide comprehensive Magic: The Gathering card information, search capabilities, price data, set information, and deck building assistance.
Runs as a Node.js application, with specific version requirements (Node.js 18+) for server operation.
Uses npm for package management, dependency installation, and running server commands.
Implements development guidelines following TypeScript best practices.
Supports Yarn as an alternative package manager for dependency installation.
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 t 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 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
🔍 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
- Install dependencies
- Configure environment (optional)
- Build the project
Usage
Development Mode
Production Mode
Testing
MCP 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
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:
Generate budget-friendly queries:
Discover interesting cards:
Search Cards
Get Card Details
Get Card Prices
Random Card
Search Sets
Scryfall Search Syntax
The server supports Scryfall's full search syntax:
Basic Operators
c:red
- Colortype:creature
- Type lineset:dom
- Set codecmc:3
- Converted mana costpower>=4
- Power/toughness comparisonslegal:modern
- Format legality
Advanced Operators
is:commander
- Card propertiesyear:2023
- Release yearrarity:mythic
- Rarityartist:"john avon"
- Artist nameflavor:"text"
- Flavor text search
Boolean Logic
red OR blue
- Either conditioncreature AND red
- Both conditionsNOT 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
Rate Limiter Status
Health Check
Configuration
Environment Variables
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
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:
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 supportToolExecutionError
- Tool-specific execution failuresResourceError
- Resource access failuresPromptError
- Prompt generation failures
Domain-Specific Errors:
ScryfallAPIError
- Scryfall API-related errorsRateLimitError
- Rate limiting and throttlingValidationError
- 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:
Health Check Monitoring
Enhanced health checks with detailed service status:
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:
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
Clear Cache
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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
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
- AsecurityFlicenseAqualityEnables 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 -7177JavaScript
- -securityFlicense-qualityA 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
- -securityFlicense-qualityEnables 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 -2Python
- AsecurityFlicenseAqualityA 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 -516023TypeScript