AnkiMCP-Server (Add-on)

Ein Anki-Add-on, das deine Sammlung über das Model Context Protocol (MCP) für KI-Assistenten zugänglich macht.

Was ist das?

Der AnkiMCP-Server führt einen lokalen MCP-Server innerhalb von Anki aus, wodurch KI-Assistenten wie Claude mit deiner Karteikartensammlung interagieren können. Dies ermöglicht KI-gestützte Lernsitzungen, das Erstellen von Karten und die Verwaltung der Sammlung.

Teil des ankimcp.ai-Projekts.

Related MCP server: Anki MCP Server

Hinweis zum ersten Start

Beim ersten Start lädt dieses Add-on pydantic_core (~2 MB) von PyPI herunter. Dies ist erforderlich, da pydantic_core plattformspezifische Binärdateien (Windows/macOS/Linux) enthält, die nicht in einer einzelnen Add-on-Datei gebündelt werden können.

Funktionen

• Lokaler HTTP-Server – Läuft standardmäßig unter http://127.0.0.1:3141/

• MCP-Protokoll – Kompatibel mit jedem MCP-Client (Claude Desktop, etc.)

• Auto-Start – Der Server startet automatisch, wenn Anki geöffnet wird

• Tunnel-freundlich – Funktioniert mit Cloudflare Tunnel, ngrok, etc.

• Plattformübergreifend – Funktioniert unter macOS, Windows und Linux (x64 und ARM)

Installation

Über AnkiWeb (empfohlen)

1. Öffne Anki und gehe zu Extras → Add-ons → Add-ons herunterladen...

2. Gib den Code ein: 124672614

3. Starte Anki neu

Über GitHub Releases

1. Lade anki_mcp_server.ankiaddon von den Releases herunter

2. Doppelklicke zum Installieren oder verwende Extras → Add-ons → Aus Datei installieren...

3. Starte Anki neu

NixOS

Mit Flakes (empfohlen)

Füge den Flake-Input hinzu und verwende das vorgefertigte Paket:

# flake.nix
{
  inputs.anki-mcp.url = "github:ankimcp/anki-mcp-server-addon";

  outputs = { nixpkgs, anki-mcp, ... }: {
    # Option A: Standalone — Anki with the addon pre-installed
    environment.systemPackages = [
      anki-mcp.packages.${system}.default
    ];

    # Option B: Composable with other addons via overlay
    nixpkgs.overlays = [ anki-mcp.overlays.default ];
    environment.systemPackages = [
      (pkgs.anki.withAddons [ pkgs.ankiAddons.anki-mcp-server ])
    ];
  };
}

Ohne Flakes

# configuration.nix
{ pkgs, ... }:
let
  python3 = pkgs.python3;

  ankiMcpPythonDeps = python3.withPackages (ps: with ps; [
    mcp pydantic pydantic-settings starlette uvicorn anyio httpx websockets
  ]);

  anki-mcp-server = pkgs.anki-utils.buildAnkiAddon (finalAttrs: {
    pname = "anki-mcp-server";
    version = "0.13.0";
    src = pkgs.fetchFromGitHub {
      owner = "ankimcp";
      repo = "anki-mcp-server-addon";
      rev = "v${finalAttrs.version}";
      hash = ""; # nix will tell you the correct hash on first build
    };
    sourceRoot = "${finalAttrs.src.name}/anki_mcp_server";
  });

  ankiWithMcp = pkgs.anki.withAddons [ anki-mcp-server ];

  ankiWrapped = pkgs.symlinkJoin {
    name = "anki-with-mcp";
    paths = [ ankiWithMcp ];
    nativeBuildInputs = [ pkgs.makeWrapper ];
    postBuild = ''
      wrapProgram $out/bin/anki \
        --prefix PYTHONPATH ':' "${ankiMcpPythonDeps}/${python3.sitePackages}"
    '';
  };
in
{
  environment.systemPackages = [ ankiWrapped ];
}

Verwendung

Der Server startet automatisch, wenn du Anki öffnest. Überprüfe den Status über Extras → AnkiMCP Server Settings...

Verbindung mit Claude Desktop

Erfordert ein installiertes Node.js. Füge dies zu deiner Claude Desktop-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3141"]
    }
  }
}

Hinweis: Claude Desktop unterstützt nativ keine HTTP-Server in seiner JSON-Konfiguration – mcp-remote überbrückt die Verbindung via stdio.

Verbindung mit Claude Code

claude mcp add anki --transport http http://127.0.0.1:3141/

Konfiguration

Bearbeitung über Ankis Extras → Add-ons → AnkiMCP Server → Konfiguration:

{
  "mode": "http",
  "http_port": 3141,
  "http_host": "127.0.0.1",
  "http_path": "",
  "cors_origins": [],
  "cors_expose_headers": ["mcp-session-id", "mcp-protocol-version"],
  "auto_connect_on_startup": true,
  "disabled_tools": [],
  "media_import_dir": "",
  "media_allowed_types": [],
  "media_allowed_hosts": []
}

Tools deaktivieren

Verstecke bestimmte Tools oder Aktionen vor KI-Clients, um den Token-Verbrauch zu reduzieren:

{
  "disabled_tools": [
    "sync",
    "card_management:bury",
    "card_management:unbury"
  ]
}

• "tool_name" — deaktiviert das gesamte Tool

• "tool_name:action" — deaktiviert eine spezifische Aktion innerhalb eines Tools mit mehreren Aktionen

Deaktivierte Tools werden vollständig aus dem MCP-Schema entfernt – KI-Clients sehen sie niemals. Tippfehler in Tool-/Aktionsnamen führen zu Konsolenwarnungen.

Benutzerdefinierter Pfad

Setze http_path, um den MCP-Endpunkt unter einem benutzerdefinierten Pfad bereitzustellen. Nützlich, wenn Anki über einen Tunnel (Cloudflare, ngrok) freigegeben wird, um einen vollständig offenen Endpunkt zu vermeiden:

{
  "http_path": "my-secret-path"
}

Der Server ist dann unter http://localhost:3141/my-secret-path/ statt unter dem Root-Verzeichnis erreichbar. Leer lassen für Standardverhalten.

CORS-Konfiguration

Um browserbasierte MCP-Clients (wie den webbasierten MCP Inspector) zuzulassen, füge erlaubte Ursprünge hinzu:

{
  "cors_origins": ["https://inspector.example.com", "http://localhost:5173"]
}

Verwende ["*"], um alle Ursprünge zuzulassen (für die Produktion nicht empfohlen).

Die Einstellung cors_expose_headers steuert, welche Antwort-Header Browser lesen können. Die Standardwerte (mcp-session-id, mcp-protocol-version) sind erforderlich, damit das MCP Streamable HTTP-Protokoll in Browsern funktioniert.

Mediensicherheit

Danke an Hideaki Takahashi (Columbia University) für die verantwortungsvolle Offenlegung der Media-Path-Traversal-Schwachstelle.

Das Tool store_media_file validiert alle Eingaben, um Path-Traversal- und SSRF-Angriffe zu verhindern:

• Dateipfade sind auf Mediendateien beschränkt (Bilder, Audio, Video) durch MIME-Typ-Prüfung

• URLs müssen http:// oder https:// verwenden und dürfen nicht auf private/interne Netzwerke zielen

• Dateinamen werden bereinigt, um Path-Traversal-Sequenzen zu entfernen

Optionale Härtung über die Konfiguration:

{
  "media_import_dir": "/Users/me/anki-media",
  "media_allowed_types": ["application/pdf"],
  "media_allowed_hosts": ["192.168.1.50", "my-nas.local"]
}

• media_import_dir — beschränkt Dateipfad-Importe auf diesen Verzeichnisbaum (leer = keine Beschränkung)

• media_allowed_types — erlaubt zusätzliche MIME-Typen über Bild/Audio/Video hinaus

• media_allowed_hosts — erlaubt spezifischen Hosts, die Blockierung privater Netzwerke zu umgehen

Verfügbare Tools

Essenzielle Tools

FSRS-Tools

GUI-Tools

Diese Tools interagieren mit der Benutzeroberfläche von Anki:

Ressourcen

Prompts

Anforderungen

• Anki 25.07 oder neuer (enthält Python 3.13)

• Anki 25.02 und älter enthalten Python 3.9, was nicht unterstützt wird — das MCP SDK erfordert Python 3.10+ (#8)

Architektur

Das Add-on führt einen MCP-Server in einem Hintergrund-Thread mit HTTP-Transport (FastMCP + uvicorn) aus. Alle Anki-Operationen werden über ein Warteschlangensystem an den Qt-Haupt-Thread überbrückt, nach demselben bewährten Muster wie AnkiConnect.

Details findest du in der Anki Add-on Development Documentation.

Entwicklung

E2E-Tests ausführen

E2E-Tests laufen gegen eine echte Anki-Instanz in Docker unter Verwendung von headless-anki.

# Install test dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

# Build the addon
./package.sh

# Start Anki container
cd .docker && docker compose up -d && cd ..

# Run tests (waits for server automatically)
pytest tests/e2e/ -v

# Stop container
cd .docker && docker compose down

Oder verwende die Makefile-Shortcuts:

make e2e        # Build, start container, run tests, stop
make e2e-up     # Just start container
make e2e-test   # Just run tests
make e2e-down   # Just stop container

CI

E2E-Tests laufen automatisch bei Push auf einen beliebigen Branch und bei PRs auf main. Siehe .github/workflows/e2e.yml.

Lizenz

AGPL-3.0-or-later

Links

• ankimcp.ai - Projekt-Homepage

• MCP Protocol - Spezifikation des Model Context Protocol

• Anki Add-on Docs - Offizielle Dokumentation zur Anki-Add-on-Entwicklung