Scryfall MCP Server

Instructions

Implementation Reference

• index.ts:250-254 (handler)

  The main handler function that fetches the card from Scryfall API using the provided ID and returns the processed response.

  async function handleGetCardById(id: string) {
    const url = `https://api.scryfall.com/cards/${encodeURIComponent(id)}`;
    const response = await fetch(url);
    return handleScryfallResponse(response);
  }

• index.ts:90-105 (schema)

  Tool schema definition including name, description, and input schema requiring a string 'id' parameter.

  const GET_CARD_BY_ID_TOOL: Tool = {
    name: "get_card_by_id",
    description:
      "Retrieve a card by its Scryfall ID (a 36-char UUID). Returns the card data in JSON.",
    inputSchema: {
      type: "object",
      properties: {
        id: {
          type: "string",
          description:
            "The Scryfall UUID, e.g. 'c09c71fb-7acb-4ffb-a47b-8961a0cf4990'"
        }
      },
      required: ["id"]
    }
  };

• index.ts:186-194 (registration)

  Registration of the tool in the SCRYFALL_TOOLS array, which is returned by the listTools handler.

  const SCRYFALL_TOOLS = [
    SEARCH_CARDS_TOOL,
    GET_CARD_BY_ID_TOOL,
    GET_CARD_BY_NAME_TOOL,
    RANDOM_CARD_TOOL,
    GET_RULINGS_TOOL,
    GET_PRICES_BY_ID_TOOL,
    GET_PRICES_BY_NAME_TOOL
  ] as const;

• index.ts:378-381 (registration)

  Dispatch case in the callToolRequest handler that invokes the get_card_by_id handler.

  case "get_card_by_id": {
    const { id } = args as { id: string };
    return await handleGetCardById(id);
  }

• index.ts:197-239 (helper)

  Shared helper function to process Scryfall API responses, handling errors and formatting JSON output.

  async function handleScryfallResponse(response: Response) {
    if (!response.ok) {
      // Attempt to parse Scryfall error
      let errorObj: ScryfallError | null = null;
      try {
        errorObj = (await response.json()) as ScryfallError;
      } catch {
        // fall back to generic
      }
      if (errorObj && errorObj.object === "error") {
        return {
          content: [
            {
              type: "text",
              text: `Scryfall error: ${errorObj.details} (code=${errorObj.code}, status=${errorObj.status})`
            }
          ],
          isError: true
        };
      } else {
        return {
          content: [
            {
              type: "text",
              text: `HTTP error ${response.status}: ${response.statusText}`
            }
          ],
          isError: true
        };
      }
    }
    // If okay, parse JSON
    const data = await response.json();
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2)
        }
      ],
      isError: false
    };
  }