Scryfall MCP Server

Instructions

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;
  };