Anki MCP Server

Instructions

Implementation Reference

• src/index.ts:95-106 (handler)

  The execute function that implements the core logic for the 'createDeck' tool by calling the Anki API to create a new deck.

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

• src/index.ts:108-115 (schema)

  Zod input schema defining parameters for the 'createDeck' tool: required name and description, optional isPublic.

  parameters: z.object({
    description: z.string().describe('Description of the deck'),
    isPublic: z
      .boolean()
      .optional()
      .describe('Whether the deck should be public'),
    name: z.string().describe('Name of the deck'),
  }),

• src/index.ts:93-116 (registration)

  The server.addTool call that registers the 'createDeck' tool with FastMCP, including name, description, handler, and schema.

  server.addTool({
    description: 'Create a new Anki deck',
    execute: async args => {
      try {
        const data = await ankiApiRequest('POST', '/api/v1/decks', {
          description: args.description,
          isPublic: args.isPublic || false,
          name: args.name,
        });
        return JSON.stringify(data, null, 2);
      } catch (error) {
        return `Error: ${error instanceof Error ? error.message : String(error)}`;
      }
    },
    name: 'createDeck',
    parameters: z.object({
      description: z.string().describe('Description of the deck'),
      isPublic: z
        .boolean()
        .optional()
        .describe('Whether the deck should be public'),
      name: z.string().describe('Name of the deck'),
    }),
  });

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

  Helper function for making authenticated HTTP requests to the Anki API, used by the 'createDeck' handler and other tools.

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