Scryfall MCP Server

Instructions

Implementation Reference

• src/mcp-server.ts:140-149 (handler)

  Executes the tool: builds Scryfall query for mana value (mv>=min mv<=max), optional color>=colors, type:quoted(type), searches, summarizes results into {total, results: CardSummary[]}.

  async ({ min, max, colors = [], type, page }: { min?: number; max?: number; colors?: Array<"W" | "U" | "B" | "R" | "G">; type?: string; page?: number }) => {
      const range = [typeof min === "number" ? `mv>=${min}` : undefined, typeof max === "number" ? `mv<=${max}` : undefined];
      const colorPart = colors.length ? `color>=${colors.join("")}` : undefined;
      const typePart = type ? `type:${quote(type)}` : undefined;
      const q = joinParts([...range, colorPart, typePart]);
      const data: any = (await Scryfall.searchCards({ q, page })) as any;
      const items: any[] = Array.isArray(data?.data) ? data.data : [];
      const out = { total: Number(data?.total_cards ?? items.length), results: items.map(summarize) };
      return { structuredContent: out } as any;
  }

• src/mcp-server.ts:124-131 (schema)

  Input schema (min/max cmc, colors array, type str, page) and output schema reference (reuses search_by_colors output: {total: number, results: CardSummary[]}).

  const searchByCmcInput = {
      min: z.number().int().min(0).optional(),
      max: z.number().int().min(0).optional(),
      colors: z.array(z.enum(["W", "U", "B", "R", "G"])).min(0).max(5).optional(),
      type: z.string().optional(),
      page: z.number().int().min(1).optional()
  } as const;
  const searchByCmcOutput = searchByColorsOutput;

• src/mcp-server.ts:132-150 (registration)

  Registers the 'search_by_cmc' tool with MCP server, providing title, description, input/output schemas, and inline handler.

  server.registerTool(
      "search_by_cmc",
      {
          title: "Search by mana value",
          description: "Find cards within a mana value range, optionally filtered by color and type.",
          inputSchema: searchByCmcInput,
          outputSchema: searchByCmcOutput
      },
      async ({ min, max, colors = [], type, page }: { min?: number; max?: number; colors?: Array<"W" | "U" | "B" | "R" | "G">; type?: string; page?: number }) => {
          const range = [typeof min === "number" ? `mv>=${min}` : undefined, typeof max === "number" ? `mv<=${max}` : undefined];
          const colorPart = colors.length ? `color>=${colors.join("")}` : undefined;
          const typePart = type ? `type:${quote(type)}` : undefined;
          const q = joinParts([...range, colorPart, typePart]);
          const data: any = (await Scryfall.searchCards({ q, page })) as any;
          const items: any[] = Array.isArray(data?.data) ? data.data : [];
          const out = { total: Number(data?.total_cards ?? items.length), results: items.map(summarize) };
          return { structuredContent: out } as any;
      }
  );

• src/mcp-server.ts:99-102 (schema)

  Shared output schema {total: number, results: array of summarized cards}, referenced by searchByCmcOutput.

  const searchByColorsOutput = {
      total: z.number().int().nonnegative(),
      results: z.array(z.object(cardSummaryShape))
  } as const;

• src/mcp-server.ts:36-46 (helper)

  Helper to summarize Scryfall card data into CardSummary shape used in output results.

  const summarize = (card: any): CardSummary => ({
      name: card?.name,
      mana_cost: card?.mana_cost,
      type_line: card?.type_line,
      oracle_text: card?.oracle_text,
      set: card?.set,
      collector_number: String(card?.collector_number ?? ""),
      scryfall_uri: card?.scryfall_uri,
      image: card?.image_uris?.normal ?? card?.image_uris?.large ?? card?.image_uris?.small,
      prices: card?.prices
  });