search_cards
Search Magic: The Gathering cards using Scryfall's full-text syntax to find specific cards, art variants, or printings with customizable filters and sorting options.
Instructions
Search cards using Scryfall's powerful full-text syntax.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Scryfall search query, e.g., 't:creature cmc<=3' | |
| unique | No | ||
| order | No | ||
| dir | No | ||
| page | No | ||
| include_extras | No | ||
| include_multilingual | No | ||
| include_variations | No |
Implementation Reference
- src/mcp-server.ts:85-88 (handler)The handler function for the 'search_cards' tool. It takes search parameters, calls Scryfall.searchCards, and returns the raw JSON response as text content.
async (params: SearchParams): Promise<ToolResult> => { const data: unknown = await Scryfall.searchCards(params); return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] } as any; } - src/mcp-server.ts:50-77 (schema)Zod shape defining the input schema for the search_cards tool, matching Scryfall's SearchParams.
const searchParamsShape = { q: z.string().describe("Scryfall search query, e.g., 't:creature cmc<=3'"), unique: z.enum(["cards", "art", "prints"]).optional(), order: z .enum([ "name", "set", "released", "rarity", "color", "usd", "tix", "eur", "cmc", "power", "toughness", "edhrec", "penny", "artist", "review" ]) .optional(), dir: z.enum(["auto", "asc", "desc"]).optional(), page: z.number().int().min(1).optional(), include_extras: z.boolean().optional(), include_multilingual: z.boolean().optional(), include_variations: z.boolean().optional() } as const; - src/mcp-server.ts:79-89 (registration)Registration of the 'search_cards' tool with the MCP server, including name, schema, description, and handler.
server.registerTool( "search_cards", { description: "Search cards using Scryfall's powerful full-text syntax.", inputSchema: searchParamsShape }, async (params: SearchParams): Promise<ToolResult> => { const data: unknown = await Scryfall.searchCards(params); return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] } as any; } ); - src/scryfall.ts:100-100 (helper)The Scryfall.searchCards helper method that makes the API request to /cards/search endpoint.
searchCards: (opts: SearchParams) => getJson("/cards/search", opts), - src/scryfall.ts:73-97 (schema)TypeScript type definition for SearchParams used by the searchCards method and tool input.
export type SearchParams = { q: string; unique?: "cards" | "art" | "prints"; order?: | "name" | "set" | "released" | "rarity" | "color" | "usd" | "tix" | "eur" | "cmc" | "power" | "toughness" | "edhrec" | "penny" | "artist" | "review"; dir?: "auto" | "asc" | "desc"; page?: number; include_extras?: boolean; include_multilingual?: boolean; include_variations?: boolean; };