scryfall-mcp 0.0.4

A Model Context Protocol (MCP) server that provides access to the Scryfall API for Magic: The Gathering card data.

Scryfall MCP Server

A Model Context Protocol (MCP) server that provides access to the Scryfall API for Magic: The Gathering card data. This server enables AI assistants and other MCP clients to search for cards, retrieve card information, download high-resolution images, and access comprehensive MTG data through a standardized interface.

Features

• Card Search: Search for Magic: The Gathering cards using Scryfall's powerful search syntax
• Card Details: Retrieve detailed information about specific cards including prices, legality, and metadata
• Image Downloads: Download high-resolution card images and art crops with automatic organization
• Database Operations: Manage local card databases with integrity verification and cleanup tools
• Set Information: Access information about MTG sets and expansions
• Artwork Access: Get high-quality card artwork and images in multiple formats
• Advanced Filtering: Use Scryfall's advanced search operators for precise queries
• Version Management: Support for downloading specific card versions by set and collector number
• Rate Limiting: Built-in rate limiting to respect Scryfall API guidelines

Installation

Install the package from PyPI:

pip install scryfall-mcp

Or install from source:

git clone https://github.com/kaminaduck/scryfall-mcp.git
cd scryfall-mcp
pip install -e .

Quick Start

Running the Server

Start the MCP server:

python -m scryfall_mcp

Or run directly:

from scryfall_mcp import main
main()

Basic Usage

The server provides several tools that can be used by MCP clients:

Search for Cards

# Search for Lightning Bolt cards
result = mcp_search_cards("lightning bolt")

# Search for red creatures with converted mana cost 3
result = mcp_search_cards("t:creature c:red cmc:3")

# Search for cards in a specific set
result = mcp_search_cards("set:znr")

Download Card Images

# Download a specific card image
result = mcp_download_card("Lightning Bolt")

# Download from a specific set
result = mcp_download_card("Lightning Bolt", set_code="m10", collector_number="146")

# Force re-download
result = mcp_download_card("Lightning Bolt", force_download=True)

Download Art Crops

# Download art crop for a card
result = mcp_download_art_crop("Lightning Bolt")

# Download art crop from specific printing
result = mcp_download_art_crop("Lightning Bolt", set_code="m10", collector_number="146")

Available Tools

Search Tools

• mcp_search_cards(query): Search for cards using Scryfall syntax
• mcp_get_card_artwork(card_id): Get artwork URLs for a specific card

Download Tools

• mcp_download_card(card_name, set_code?, collector_number?, force_download?): Download high-resolution card images
• mcp_download_art_crop(card_name, set_code?, collector_number?, force_download?): Download art crop images

Database Tools

• mcp_verify_database(): Verify database integrity
• mcp_scan_directory(directory, update_db?): Scan directories for image files
• mcp_clean_database(execute?): Clean database of missing file references
• mcp_database_report(): Generate comprehensive database report

Available Resources

Card Resources

• resource://card/{card_id}: Get detailed card information by Scryfall ID
• resource://card/name/{card_name}: Get detailed card information by name
• resource://random_card: Get a random Magic: The Gathering card

Database Resources

• resource://database/stats: Get database statistics and information

Search Syntax

The server supports Scryfall's powerful search syntax. Here are some examples:

Query	Description
lightning bolt	Cards with "lightning bolt" in the name
t:creature	All creature cards
c:red	All red cards
cmc:3	Cards with converted mana cost 3
set:znr	Cards from Zendikar Rising
r:mythic	Mythic rare cards
pow>=4	Creatures with power 4 or greater
o:"draw a card"	Cards with "draw a card" in rules text
is:commander	Cards that can be commanders
year:2023	Cards printed in 2023

Advanced Search Examples

# Find all red creatures with power 4 or greater from recent sets
mcp_search_cards("t:creature c:red pow>=4 year>=2020")

# Find all planeswalkers that cost 3 mana
mcp_search_cards("t:planeswalker cmc:3")

# Find all cards with "flying" and "vigilance"
mcp_search_cards("o:flying o:vigilance")

# Find all legendary creatures that can be commanders
mcp_search_cards("t:legendary t:creature is:commander")

# Find all cards illustrated by a specific artist
mcp_search_cards("a:\"Rebecca Guay\"")

Configuration

The server uses the following default directories:

• Card Images: ~/.scryfall_mcp/card_images/
• Art Crops: .local/scryfall_images/ (organized by set)
• Database: .local/scryfall_db.sqlite - SQLite database for tracking downloads

Error Handling

All tools return structured responses with status indicators:

{
    "status": "success" | "error",
    "message": "Description of result or error",
    "data": {...}  # Additional response data
}

Requirements

• Python 3.12+
• httpx >= 0.28.1
• mcp[cli] >= 1.8.0
• build >= 1.2.2.post1
• twine >= 6.1.0

Development

Setting up Development Environment

git clone https://github.com/kaminaduck/scryfall-mcp.git
cd scryfall-mcp
pip install -e ".[dev]"

Code Style

This project follows PEP 8 style guidelines and includes comprehensive docstrings following the project's documentation standards.

API Reference

Tool Signatures

def mcp_search_cards(query: str) -> Dict[str, Any]
def mcp_download_card(card_name: str, set_code: Optional[str] = None, 
                     collector_number: Optional[str] = None, 
                     force_download: bool = False) -> Dict[str, Any]
def mcp_download_art_crop(card_name: str, set_code: Optional[str] = None,
                         collector_number: Optional[str] = None,
                         force_download: bool = False) -> Dict[str, Any]
def mcp_get_card_artwork(card_id: str) -> Dict[str, Any]
def mcp_verify_database() -> Dict[str, Any]
def mcp_scan_directory(directory: str, update_db: bool = False) -> Dict[str, Any]
def mcp_clean_database(execute: bool = False) -> Dict[str, Any]
def mcp_database_report() -> Dict[str, Any]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Scryfall for providing the comprehensive Magic: The Gathering API
• Model Context Protocol for the standardized interface
• The Magic: The Gathering community for their continued support

Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information about your problem
3. Include relevant error messages and system information

---

Note: This is an unofficial tool and is not affiliated with Wizards of the Coast or Scryfall. Magic: The Gathering is a trademark of Wizards of the Coast LLC.