Anki Flashcard MCP Server 🃏

Project Overview 🚀

This project provides a Dockerized Model Context Protocol (MCP) server specifically designed to work with the Anki desktop application. By leveraging the anki-flashcard-mcp server, you can use a large language model (LLM), such as Claude, to automatically generate flashcards and sync them with your Anki decks.

Prerequisites ✅

Before you get started, please make sure you have the following installed:

• Docker: The containerization platform. 🐳
• uv: A fast Python package installer and bundler (recommended for development).
• AnkiConnect Add-on: This Anki add-on is required to allow the server to communicate with your Anki application. In Anki, go to Tools > Add-ons > Get Add-ons... and enter the code 2055492159.
• Anki Desktop: The Anki application must be open and running for the server to work. 💡

Development Setup (Optional) ⚙️

If you plan to develop or modify the server, you can set it up locally using uv.

1. Initialize the project:

uvx create-mcp-server anki-flashcard-mcp
cd anki-flashcard-mcp

2. Install dependencies and run the server:

uv sync --dev --all-extras
uv run my-server

Running with Docker 📦

This is the recommended way to use the server.

1. Build the Docker image:

docker build -t anki-flashcard-mcp .

This command builds the Docker image and tags it as anki-flashcard-mcp.

2. Test the server (optional): You can test the container using the MCP inspector tool to ensure it's running correctly.

npx @modelcontextprotocol/inspector docker run -i --rm --init -e DOCKER_CONTAINER=true anki-flashcard-mcp

This command will run the inspector, which lets you test prompts and tools to verify the container's output.

Using with the Claude App 🤖

Follow these steps to integrate the Dockerized server with the Claude desktop application.

1. Enable Docker access for Claude: Sometimes, Claude doesn't have the necessary shell environment variables to access Docker. Run the following command in your terminal to fix this:

launchctl setenv PATH "$PATH"

2. Configure Claude Desktop:
   • Open the Claude app and navigate to Settings > Developer.
   • Find the Local MCP Servers section and click Edit Config.
   • This will open claude_desktop_config.json. Add the following configuration to the JSON file:

{
  "mcpServers": {
    "anki-flashcard-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "DOCKER_CONTAINER=true",
        "anki-flashcard-mcp"
      ]
    }
  }
}

3. Troubleshooting - Wrapper Script (if direct config fails): ⚠️ If the direct configuration doesn't work, you can use a shell script as a stable entry point.
   • Create a new script file, for example: /Users/cademaxwell/.scripts/run-anki-docker.sh

#!/bin/bash
exec /usr/local/bin/docker run -i --rm --init -e DOCKER_CONTAINER=true anki-flashcard-mcp

• Make the script executable:

chmod +x ~/.scripts/run-anki-docker.sh

• Note: Replace /usr/local/bin/docker with the actual path to your Docker executable (you can find this by running which docker).
• Update the claude_desktop_config.json to point to the new script:

{
  "mcpServers": {
    "anki-flashcard-mcp": {
      "command": "/Users/cademaxwell/.scripts/run-anki-docker.sh"
    }
  }
}

Your Dockerized MCP server is now ready to be used by Claude! Each time you open the Claude desktop app, a new Docker container will start for the anki-flashcard-mcp image.