Anki MCP Server

Instructions

Implementation Reference

• src/index.ts:121-134 (handler)

  The main handler function for the 'addCardsBatch' tool. It makes a POST request to the Anki API's batch cards endpoint using the shared ankiApiRequest helper.

  execute: async args => {
    try {
      const data = await ankiApiRequest(
        'POST',
        `/api/v1/decks/${args.deckId}/cards/batch`,
        {
          cards: args.cards,
        },
      );
      return JSON.stringify(data, null, 2);
    } catch (error) {
      return `Error: ${error instanceof Error ? error.message : String(error)}`;
    }
  },

• src/index.ts:136-152 (schema)

  Zod schema defining the input parameters for addCardsBatch: deckId (string) and cards (array of card objects with front, back, cardType, optional clozeText and tags).

  parameters: z.object({
    cards: z
      .array(
        z.object({
          back: z.string().describe('Back side of the card'),
          cardType: z.enum(['BASIC', 'CLOZE']).describe('Type of card'),
          clozeText: z
            .string()
            .optional()
            .describe('Cloze text for cloze cards'),
          front: z.string().describe('Front side of the card'),
          tags: z.array(z.string()).optional().describe('Tags for the card'),
        }),
      )
      .describe('Array of cards to add'),
    deckId: z.string().describe('ID of the deck to add cards to'),
  }),

• src/index.ts:119-153 (registration)

  Registration of the 'addCardsBatch' tool via server.addTool call, including description, handler, name, and parameters schema.

  server.addTool({
    description: 'Add multiple cards to a deck in batch',
    execute: async args => {
      try {
        const data = await ankiApiRequest(
          'POST',
          `/api/v1/decks/${args.deckId}/cards/batch`,
          {
            cards: args.cards,
          },
        );
        return JSON.stringify(data, null, 2);
      } catch (error) {
        return `Error: ${error instanceof Error ? error.message : String(error)}`;
      }
    },
    name: 'addCardsBatch',
    parameters: z.object({
      cards: z
        .array(
          z.object({
            back: z.string().describe('Back side of the card'),
            cardType: z.enum(['BASIC', 'CLOZE']).describe('Type of card'),
            clozeText: z
              .string()
              .optional()
              .describe('Cloze text for cloze cards'),
            front: z.string().describe('Front side of the card'),
            tags: z.array(z.string()).optional().describe('Tags for the card'),
          }),
        )
        .describe('Array of cards to add'),
      deckId: z.string().describe('ID of the deck to add cards to'),
    }),
  });

• src/index.ts:23-63 (helper)

  Shared utility function used by addCardsBatch (and other tools) to make authenticated HTTP requests to the Anki API server.

  async function ankiApiRequest(
    method: string,
    endpoint: string,
    body?: Record<string, unknown>,
    queryParams?: Record<string, boolean | number | string | undefined>,
  ) {
    const url = new URL(`${ANKI_BASE_URL}${endpoint}`);
  
    // Add query parameters if provided
    if (queryParams) {
      Object.entries(queryParams).forEach(([key, value]) => {
        if (value !== undefined && value !== '') {
          url.searchParams.append(key, String(value));
        }
      });
    }
  
    const options: RequestInit = {
      headers: {
        Authorization: `Bearer ${ANKI_API_KEY}`,
        'Content-Type': 'application/json',
      },
      method,
    };
  
    if (body && method !== 'GET') {
      options.body = JSON.stringify(body);
    }
  
    const response = await fetch(url.toString(), options);
    const data = (await response.json()) as unknown;
  
    if (!response.ok) {
      const errorData = data as { error?: { message?: string } };
      throw new Error(
        errorData.error?.message || `API request failed: ${response.statusText}`,
      );
    }
  
    return data;
  }