Scryfall MCP Server
Use this MCP server to search and inspect MTG cards, sets, prices, rules, and deckbuilding data, and to analyze or validate decks and Brawl commanders.
Search cards with Scryfall syntax, pagination, sorting, price filters, Arena/rarity/extra/multilingual options.
Fetch card details by name, set plus collector number, or Scryfall ID, with language, face, and image controls.
Get prices in USD/EUR/TIX with format context and optional budget alternatives/upgrades; price history is marked not implemented.
Get random cards filtered by query, format, archetype, similarity, price, rarity, or reprint preference.
Search sets by name/code, type, and release date.
Query the local comprehensive rules with exact-match, section, and context controls.
Convert natural-language requests into explainable/tested Scryfall queries with format, budget, and alternative-query options.
Find format staples, budget alternatives/upgrades, and synergistic cards using disclosed heuristics.
Batch-analyze cards for legality, prices, synergy, composition, and suggestions.
Validate Brawl and Standard Brawl commander legality.
Analyze deck composition and suggest mana bases/land packages, with special mana requirements unsupported.
Access cached Oracle bulk and set-list resources, use analyze_card and build_deck prompts, and render the ChatGPT card-search widget via show_card_search.
Run locally via stdio or Streamable HTTP with health checks, caching, rate limiting, and session/auth controls.
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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Scryfall MCP Server show me budget red creatures for commander under $5"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Scryfall MCP Server
Scryfall-backed MCP server for Magic: The Gathering search, rules lookup, pricing, set discovery, and deckbuilding workflows.
The project currently supports:
stdioas the primary transport for local MCP clientslocal-first Streamable HTTP via
src/http.ts15 MCP tools, 3 resources, and 2 prompts
What It Exposes
Tools
search_cards: Run Scryfall card searches with paging, sorting, and optional price filtering.get_card: Fetch one card by name, set/collector number, or Scryfall ID.get_card_prices: Return price data with optional format context and alternatives.random_card: Get a random card with optional filters.search_sets: Search and filter Magic sets.query_rules: Search the local comprehensive rules file with context.build_scryfall_query: Convert natural language into an explainable Scryfall query.search_format_staples: Search format-legal candidates using disclosed price and ordering heuristics, not tournament metagame data.search_alternatives: Find candidates using disclosed price, type, and mana-value heuristics; results are not verified functional replacements or upgrades.find_synergistic_cards: Find synergy pieces for a card, theme, or archetype.batch_card_analysis: Analyze multiple cards for legality, prices, synergy, or composition.validate_brawl_commander: Check Brawl and Standard Brawl commander legality.analyze_deck_composition: Evaluate deck lists for curve, colors, and structural issues.suggest_mana_base: Recommend land counts and fixing packages from color requirements.show_card_search: Render a ChatGPT Apps widget for visual Scryfall card search results.
Resources
card-database://bulk: Cached Oracle bulk snapshot.set-database://all: Cached set list snapshot.ui://widget/card-search.html: ChatGPT Apps widget template forshow_card_search.
Prompts
analyze_cardbuild_deck
Related MCP server: MTG-MCP
Transports
STDIO
Recommended for Claude Desktop, Codex, MCP Inspector, and most local MCP clients.
npm run devnpm startStreamable HTTP
Available as a separate entrypoint for local or explicitly controlled environments.
npm run dev:httpnpm run start:httpFor local MCP testing:
npm run dev:http:local
npm run smoke:httpThe smoke test checks /health, performs MCP initialize, sends notifications/initialized, and verifies tools/list.
It also makes representative validate_brawl_commander and search_cards tool calls so the local HTTP endpoint is checked beyond discovery.
HTTP requests retain a default 1 MiB body limit (HTTP_MAX_BODY_BYTES). Before SDK
or tool validation, the HTTP entrypoint also rejects request JSON containing more
than 10,000 array elements and object keys in total. This applies across the whole
request, including batches; SDK 1.32.2 additionally caps batches at 100 messages.
The structural guard is iterative and applies to this project's low-level Server
handlers; it does not rely on the opt-in McpServer.maxToolInputElements option.
Current HTTP behavior:
binds to
127.0.0.1by defaultserves
POST|GET|DELETEon/mcpserves
GET /healthrejects non-loopback
Originheaders by default unlessHTTP_ALLOWED_ORIGINSis setrequires both
HTTP_AUTH_TOKENandHTTP_TRUST_PROXY_TLS=truewhenHTTP_HOSTis not loopback; the latter is an operator assertion that a trusted HTTPS proxy or tunnel protects the plaintext listenerlimits active and initializing sessions with
HTTP_MAX_SESSIONS(default100)
The HTTP entrypoint is useful today, but it is still documented conservatively. It is not presented here as a public-hosting story.
ChatGPT App Development
The HTTP MCP endpoint can be connected to ChatGPT Developer Mode as a local app prototype. Start the server on loopback:
npm run dev:http:localExpose that local endpoint with an HTTPS tunnel:
ngrok http 3000Then connect the tunneled https://.../mcp URL in ChatGPT Developer Mode. Refresh the app after changing tool descriptors, widget resources, or metadata so ChatGPT reloads the current MCP surface.
The current ChatGPT-facing widget is show_card_search, which returns concise structuredContent for the model and renders ui://widget/card-search.html in ChatGPT. The widget is read-only against Scryfall, uses Scryfall image URLs, and keeps its CSP resource allowlist limited to https://cards.scryfall.io.
Setup
Prerequisites
Node.js
^20.19.0,^22.13.0, or>=24.0.0npm
Install
git clone https://github.com/bmurdock/scryfall-mcp.git
cd scryfall-mcp
npm install
cp .env.example .envThe documented npm run dev*, npm start, and npm run inspector commands preload .env. Explicit process environment variables take precedence over values in that file. MCP clients that launch dist/index.js directly should provide overrides through their own env configuration.
Validate
npm run lint
npm run type-check
npm test
npm run test:coverageLint rejects warnings. Tests capture application warning, error, and fatal logs;
failure-path tests declare expected diagnostics with expectLog from
tests/helpers/expected-logs.ts. Missing or unexpected diagnostics fail the test.
Build
npm run buildCommon Commands
npm run dev
npm run dev:http
npm start
npm run start:http
npm test
npm run test:watch
npm run test:ui
npm run test:coverage
npm run lint
npm run lint:fix
npm run type-check
npm run inspectorConfiguration
See .env.example for the canonical values. The main variables in active use are:
SCRYFALL_USER_AGENTRATE_LIMIT_MSRATE_LIMIT_QUEUE_MAXSCRYFALL_TIMEOUT_MSCACHE_MAX_SIZECACHE_MAX_MEMORY_MBLOG_LEVELNODE_ENVHEALTHCHECK_DEEPHTTP_HOSTHTTP_PORTHTTP_MCP_PATHHTTP_HEALTH_PATHHTTP_MAX_BODY_BYTESHTTP_SESSION_IDLE_MSHTTP_SESSION_CLEANUP_INTERVAL_MSHTTP_ALLOWED_ORIGINSHTTP_AUTH_TOKENHTTP_TRUST_PROXY_TLSHTTP_MAX_SESSIONS
Operational notes:
query_rulesaccepts up to 2,000 characters and 32 distinct words. Flexible matching requires every term; scans yield periodically so request cancellation can interrupt them.Search price bounds apply to the complete query, including all
ORbranches. Search inputs support mana-symbol braces, split-card separators, and Unicode names.Natural-language numeric price constraints require monetary context, such as
$,tix, orprice; power and mana comparisons are not treated as prices. Query testing treats Scryfall's no-match HTTP 404 as an empty result eligible for broadening while retaining an explicitprice_budgetcap.Natural-language queries preserve
€price constraints and distinguish whole color words, negated colors, exact colors, and multicolor requests. Price explanations retain USD, EUR, or TIX units.Deck composition reports a nonland average mana value for curve advice. Displayed curves include lands, and batch analysis groups all mana values of seven or more into one
7+bucket.Scryfall API calls are globally serialized by the shared rate limiter. Batch tools may schedule multiple local lookups, but upstream Scryfall request completion remains one-at-a-time by design.
The default pacing is 100 ms for general API endpoints and at least 500 ms for Scryfall's 2/sec card endpoints:
/cards/search,/cards/named,/cards/random, and/cards/collection.HTTP 429 responses are not retried automatically. The server records Scryfall's throttle window and delays the next request start so callers can decide whether to retry.
Throttle windows accept both seconds and HTTP-date
Retry-Aftervalues, including when a 429 response has a non-JSON body.CACHE_MAX_MEMORY_MBcontrols whether large in-memory snapshots, includingcard-database://bulk, can be retained. Bulk resource rebuilds stream to a temp file first; oversized snapshots remain on disk for warm reads instead of being retained in the cache. Each MCP resource response still materializes the complete serialized bulk payload required by the resource protocol, so callers should allow memory proportional to that response size.Set snapshots are refreshed weekly. A stale snapshot may be retained for up to four weeks, subject to cache capacity, and served when a scheduled refresh fails; failed scheduled refreshes are retried after five minutes.
Concurrent set-cache misses share one upstream fetch while applying each caller's filters separately. Set searches reject impossible calendar dates.
Card detail output includes Scryfall source links and artist attribution when available. Consumers that render Scryfall image URLs should preserve copyright, artist, and source context and should not crop, distort, recolor, watermark, or imply ownership of card images.
Non-English
get_cardlookups use Scryfall's localized set/collector endpoint. Name and UUID lookups first resolve a printing, then request that printing in the selected language; unavailable translations return a lookup error.get_card_pricesuses a separate six-hour cache, independent of the 24-hour card-detail cache.When requested price comparisons fail,
get_card_pricesretains the base price and identifies unavailable comparison categories. A throttled comparison stops further comparison requests and includes available retry guidance.Deck-list analysis resolves card names exactly first, then falls back to fuzzy lookup for exact misses and reports any fuzzy resolutions in the response. Input is bounded to 64 KiB, 100 unique names, 10,000 total cards, and 1,000 copies per entry.
Cancelling an MCP tool, prompt, or resource read stops its queued Scryfall work. A lookup or resource read shared with another active caller continues until that caller completes or cancels. Bulk resource cancellation stops the stream and cleans up the incomplete snapshot; shutdown waits for active bulk rebuild cleanup.
The stdio server shuts down when its client closes input. Malformed HTTP URLs or Host headers return HTTP 400 without terminating the server.
Prompt validation errors retain their actionable message and use the MCP invalid-parameters error code. Upstream prompt errors include safe status or retry information.
suggest_mana_basereturns heuristic land counts and cycle categories; individual card legality and color compatibility still require verification. All allocated slots are included, with a generic fixing category when no specific cycle is available. Special land requirements are currently unsupported and nonemptyspecial_requirementsinputs return a validation error.Deck-scale tools may return partial analysis or an explicit retry-after message when Scryfall throttles the underlying card lookups.
Streamable HTTP sessions expire after
HTTP_SESSION_IDLE_MSand are checked byHTTP_SESSION_CLEANUP_INTERVAL_MS.Requests with expired or unknown HTTP session IDs return 404; clients recover by initializing a new session without the old ID. Requests missing a required session ID return 400.
Non-loopback HTTP bindings require bearer-token authentication and
HTTP_TRUST_PROXY_TLS=true, which asserts that a trusted HTTPS proxy or tunnel protects the plaintext listener. Origin allowlists remain an additional browser policy, not an authentication mechanism.GET /healthis a readiness check: it returns HTTP 503 when a required service is degraded, including while the Scryfall circuit breaker is open.
Example local HTTP startup:
HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:httpExample Tool Calls
build_scryfall_query
{
"natural_query": "blue counterspells under $20 for modern",
"optimize_for": "precision"
}search_cards
{
"query": "c:r t:instant mv=1",
"limit": 10,
"order": "name"
}search_sets
{
"type": "expansion",
"released_after": "2020-01-01"
}find_synergistic_cards
{
"focus_card": "Obeka, Splitter of Seconds",
"synergy_type": "theme",
"format": "commander",
"color_identity": "UBR",
"limit": 12
}For commander-like workflows, pass color_identity when the focus is a theme rather than a resolvable card. When the focus resolves to a card, the tool infers that card's color identity and filters final results by requested legality, Arena availability, and color identity.
analyze_deck_composition
{
"deck_list": "4 Lightning Bolt\n4 Monastery Swiftspear\n20 Mountain",
"format": "modern",
"strategy": "aggro"
}Claude Desktop Integration
Add the built stdio entrypoint to your Claude Desktop configuration.
macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows path: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"scryfall": {
"command": "node",
"args": ["/absolute/path/to/scryfall-mcp/dist/index.js"]
}
}
}Operational Notes
Rate limiting is enforced in-process with a 100 ms default minimum interval between general Scryfall API requests and a 500 ms minimum for Scryfall's 2/sec card endpoints.
Search responses, card details, prices, sets, and bulk snapshots are cached with bounded in-memory limits.
The bulk card resource streams rebuilds through disk and stores a pre-serialized snapshot to keep repeated reads cheap. Cache retention is bounded, but producing a bulk resource response still requires the full serialized response text in process memory.
Set filtering is derived from one canonical cached
/setsdataset to avoid incorrect filtered cache reuse.Health checks are available through
ScryfallMCPServer.healthCheck()and the HTTP/healthendpoint.If an MCP connector reports a JSON-RPC/SSE deserialization error, compare it against the raw HTTP smoke path:
npm run dev:http:local
npm run smoke:httpIf the smoke command succeeds, capture the connector error text and the smoke output together; that separates local endpoint framing from connector-specific parsing.
Documentation Map
Current source-of-truth docs:
License
MIT
Available Tools
14 toolsanalyze_deck_compositionC
Analyze deck composition, mana curve, card types, and provide balance recommendations
Inputs: deck_list (required), commander, format, strategy.
batch_card_analysisC
Analyze multiple cards for legality, prices, synergies, or deck composition
Inputs: analysis_type (required), card_list (required), currency, format, +2 more.
build_scryfall_queryB
Convert natural language requests into optimized Scryfall search queries with explanations and alternatives
Inputs: natural_query (required), explain_mapping, format, include_alternatives, +4 more.
find_synergistic_cardsC
Find cards that synergize with a specific card, theme, or archetype
Inputs: focus_card (required), arena_only, exclude_colors, format, +4 more.
get_cardB
Get detailed information about a specific Magic: The Gathering card by name, set code+number, or Scryfall ID
Inputs: identifier (required), face, include_image, lang, +1 more.
get_card_pricesB
Get current price information for a Magic: The Gathering card by name, set/number, or Scryfall ID
Inputs: card_identifier (required), currency, format_context, include_alternatives, +1 more.
query_rulesC
Search Magic: The Gathering comprehensive rules for specific interactions and rule clarifications
Inputs: query (required), context_lines, exact_match, section.
random_cardB
Get a random Magic: The Gathering card, optionally filtered by format or search criteria
Inputs: archetype, exclude_reprints, format, price_range, +3 more.
search_alternativesB
Find budget alternatives, upgrades, or functionally similar cards
Inputs: direction (required), target_card (required), format, limit, +3 more.
search_cardsA
Search for Magic: The Gathering cards using Scryfall search syntax. Supports complex queries with operators like color:, type:, set:, etc.
Inputs: query (required), arena_only, direction, format, +8 more.
search_format_staplesC
Find format staples, meta cards, and role-specific cards for competitive play
Inputs: format (required), color_identity, limit, max_price, +2 more.
search_setsC
Search for Magic: The Gathering sets with optional filtering by name, type, and release dates
Inputs: query, released_after, released_before, type.
suggest_mana_baseC
Suggest optimal mana base composition and land recommendations for a deck
Inputs: color_requirements (required), average_cmc, budget, color_intensity, +4 more.
validate_brawl_commanderB
Validate if a card can be a legal commander in Brawl or Standard Brawl formats
Inputs: card_identifier (required), format (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Every tool has a clearly distinct purpose with no significant overlap. For example, get_card retrieves a single card, search_cards handles complex queries, and analyze_deck_composition focuses on deck analysis, making misselection unlikely.
All tool names follow a consistent verb_noun pattern using snake_case, such as get_card, search_cards, and analyze_deck_composition. This predictability aids in agent understanding and usage.
With 14 tools, the server is well-scoped for Magic: The Gathering card and deck management. Each tool serves a specific function, from card retrieval to deck analysis, without feeling excessive or insufficient.
The tool surface comprehensively covers the domain, including card search, price checks, deck analysis, rules queries, and format validation. There are no obvious gaps, supporting full agent workflows for MTG-related tasks.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
A Model Context Protocol server for Wix AI tools
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for I Want My MTG that enables conversational search of Magic: The Gathering cards/sets and inventory management via API tools.61418 npm1MIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive Model Context Protocol server that provides AI assistants with rich Magic: The Gathering information, including card data, comprehensive rules, EDHREC recommendations, combo interactions, and intelligent Commander deck generation.1MIT
- AlicenseAqualityDmaintenanceMCP server for searching and retrieving Magic: The Gathering card information via the Scryfall API, with support for field presets, multiple output formats, and automatic rate limiting.4MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that searches and retrieves Magic: The Gathering card data from the Scryfall API.74,083 npmMIT