A compact Model Control Protocol (MCP) service that exposes Scryfall API lookups for Magic: The Gathering cards and sets, designed for integration with large language models (LLMs).
Built with a focus on speed, stability, and native Python asynchronicity.
- Native Async: Built with httpx for purely non-blocking, high-performance I/O.
- Scryfall API: Uses the modern, reliable, and up-to-date Scryfall API.
- MCP Ready: Automatically generates tool schemas for LLM consumption using mcp.server.fastmcp.
- Robust Search: Provides fine-grained searching by name, color, type, set, and more.
Severin requires Python 3.8+ and the following dependencies:
# Install the necessary libraries
pip install httpx mcpThe service is configured under the tool name mtg.py.
To ensure stability and reliable inter-process communication, especially on Windows environments (where standard I/O pipes can be unstable), use the --stdio-port flag:
# Execute the service using your MCPO runtime
uvx mcpo --stdio-port 8000 -- python .\mtg.py
# Expected Output:
# INFO: Connected to MCP server 'mtg_scryfall' with 5 tool definitions.
# INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)The following functions are decorated with @mcp.tool() and are callable by an LLM:
| Tool Name | Description | Key Arguments |
|---|---|---|
search_cards |
Multi-field card search using Scryfall's advanced query syntax. | name, colors, type_line, rarity, set_code, oracle_text, limit |
get_sets |
Searches sets by code or name (filters locally from the full Scryfall list). | code, name |
get_card_types |
Lists primary card types (e.g., Creature, Instant). | None |
get_card_supertypes |
Lists card supertypes (e.g., Legendary, Basic). | None |
get_card_subtypes |
Lists example card subtypes (e.g., Human, Aura). | None |
API Configuration: The service uses SCRYFALL_API_BASE = https://api.scryfall.com and includes the mandatory USER_AGENT = "mtgfinder-mcp/1.0" as required by Scryfall's API policy.
The LLM will construct the tool calls based on the user request and the available schema:
| User Request | Example Tool Call |
|---|---|
| "Trova Tarmogoyf" | mtg_scryfall/search_cards(name="Tarmogoyf", limit=1) |
| "Dimmi i set di Innistrad" | mtg_scryfall/get_sets(name="Innistrad") |
| "Cerca un gobelin rosso con travolgere" | mtg_scryfall/search_cards(colors="R", type_line="Creature Goblin", oracle_text="trample") |
- Open issues and PRs on GitHub
- Keep changes focused, include tests or examples for new tools
MIT