Anki MCP

Anki MCP Server

Beta – Dieses Projekt befindet sich in aktiver Entwicklung. APIs und Funktionen können sich ändern.

Ein Model Context Protocol (MCP)-Server, der KI-Assistenten die Interaktion mit Anki, der Karteikarten-App für verteiltes Wiederholen, ermöglicht.

Verwandeln Sie Ihr Anki-Erlebnis in eine Interaktion in natürlicher Sprache – wie mit einem privaten Tutor. Der KI-Assistent präsentiert nicht nur Fragen und Antworten; er kann Konzepte erklären, den Lernprozess ansprechender und menschlicher gestalten, Kontext liefern und sich an Ihren Lernstil anpassen. Er kann Notizen spontan erstellen und bearbeiten und macht Ihre Lernsitzungen zu dynamischen Gesprächen. Weitere Funktionen folgen bald!

Beispiele und Tutorials

Für umfassende Anleitungen, praxisnahe Beispiele und Schritt-für-Schritt-Tutorials zur Verwendung dieses MCP-Servers mit Claude Desktop besuchen Sie:

ankimcp.ai – Vollständige Dokumentation mit praktischen Beispielen und Anwendungsfällen

Siehe docs/ für ergänzende Dokumentation, einschließlich der Anleitung zur Einrichtung des Reviewers und des Beispiel-Anki-Decks.

Beispielhafte Anwendungsfälle

Drei repräsentative Eingabeaufforderungen, die die Tool-Abläufe dieses Servers zeigen:

1. „Hilf mir, mein Spanisch-Deck zu wiederholen.“ – Der Assistent synchronisiert mit AnkiWeb (sync), ruft fällige Karten ab (get_due_cards mit Deck-Filter), präsentiert jede Karte (present_card) und erfasst Ihre Bewertung (rate_card). Natürliches Lerngespräch mit auf Sie zugeschnittenen Erklärungen.

2. „Erstelle 10 arabische Vokabelkarten mit RTL-Formatierung.“ – Der Assistent listet Notiztypen auf (modelNames), erstellt bei Bedarf ein benutzerdefiniertes RTL-Modell (createModel + updateModelStyling für Rechts-nach-links-CSS) und erstellt dann die Karten in Stapelverarbeitung (addNotes).

3. „Importiere dieses Bild aus meinem Downloads-Ordner in die Vorderseite der ausgewählten Notiz.“ – Der Assistent lädt die lokale Datei hoch (storeMediaFile mit einem Dateipfad), liest die aktuell im Browser ausgewählte Notiz (guiSelectedNotes + notesInfo) und aktualisiert das Vorderseiten-Feld mit einem <img>-Tag (updateNoteFields).

Verfügbare Tools

Der Server stellt 50 MCP-Tools bereit – 39 wesentliche Tools für alltägliche Anki-Operationen und 11 GUI-Tools, die die Anki-Desktop-Oberfläche für Notizbearbeitungs-/Erstellungsworkflows steuern.

Wesentliche Tools

Wiederholen & Lernen

• sync – Mit AnkiWeb synchronisieren, um neueste Daten abzurufen und Änderungen zu übertragen
• get_due_cards – Fällige Karten abrufen, optional nach Deck gefiltert (Antworten ausgelassen, außer include_answer: true, Standard false)
• get_cards – Karten mit flexibler Filterung nach Status (fällig, neu, lernend, ausgesetzt, vergraben) und Deck abrufen (Antworten ausgelassen, außer include_answer: true, Standard false)
• present_card – Eine Karte zur Wiederholung mit ihrer Frage-/Vorderseite anzeigen
• rate_card – Kartenleistung bewerten (Erneut, Schwer, Gut, Leicht) und die nächste Wiederholung planen
• forgetCards – Karten auf „Neu“ zurücksetzen, ihre Planung verwerfen, ohne eine Wiederholung zu erfassen
• setDueDate – Karten so umplanen, dass sie in N Tagen fällig werden ("0", "3-7", "1!"), ohne eine Wiederholung zu erfassen

Hinweis: forgetCards und setDueDate ändern die Planung ohne eine Wiederholung zu protokollieren, was sie von rate_card unterscheidet. Greifen Sie darauf zurück, wenn die Planung einer Karte falsch ist, statt auf die Antwort: Eine Karte mit Again zu bewerten, um sie tiefer zu vergraben, erfasst einen echten Fehlversuch und senkt ihren Leichtigkeitsfaktor, was dauerhaft sowohl die zukünftige Planung als auch Ihre Statistiken verzerrt. forgetCards löscht das Intervall und startet die Karte neu; setDueDate behält die Historie der Karte und verschiebt nur die nächste Wiederholung.

Hinweis: Der Inhalt von Karten front/back wird pro Karte aus ihrer eigenen Vorlage gerendert (wie Anki es anzeigt), sodass umgekehrte und Lückentext-Karten die richtige Richtung anzeigen. Statischer Text, der von Ihren Kartenvorlagen hinzugefügt wurde, erscheint ebenfalls in der Ausgabe.

Deck-Verwaltung

• listDecks – Alle Decks auflisten, optional mit Lernwarteschlangen-Statistiken pro Deck
• deckStats – Umfassende Statistiken für ein einzelnes Deck abrufen (Lernwarteschlange, echte Kartenstatus-Zählungen, Leichtigkeits-/Intervallverteilungen)
• createDeck – Ein neues leeres Deck erstellen (unterstützt Parent::Child, max. 2 Ebenen)
• changeDeck – Karten in ein anderes Deck verschieben (wird erstellt, falls es nicht existiert)

Hinweis: Deck-Statistiken gibt es in zwei Varianten. Der counts-Block (und alles, was listDecks meldet) spiegelt Ankis Deck-Browser wider: Karten, die heute fällig sind, begrenzt durch die täglichen Neu-/Wiederholungslimits jedes Decks, wobei ausgesetzte und vergrabene Karten ausgeschlossen sind – review ist also nicht „reife Karten“ und der other-Bucket ist nur der arithmetische Rest (meist Wiederholungskarten, die heute nicht fällig sind, plus neue Karten über dem Tageslimit). Für echte Summen pro Status verwenden Sie den states-Block auf deckStats / collection_stats, der new, learning, review, suspended und buried über Anki-Suchen zählt, ohne Fälligkeitsdaten und Tageslimits zu berücksichtigen.

Notiz-Verwaltung

• addNote – Eine einzelne Notiz mit angegebenen Feldern und Tags erstellen
• addNotes – Bis zu 100 Notizen in Stapelverarbeitung erstellen, die ein Deck und Modell teilen (teilweiser Erfolg unterstützt)
• findNotes – Notizen mit Anki-Abfragesyntax suchen (deck:, tag:, is:due usw.)
• notesInfo – Detaillierte Informationen zu Notizen abrufen (Felder, Tags, CSS-Formatierung)
• updateNoteFields – Vorhandene Notizfelder aktualisieren (CSS-bewusst, unterstützt HTML-Inhalte)
• deleteNotes – Notizen und alle zugehörigen Karten löschen (destruktiv, erfordert Bestätigung)

Tag-Verwaltung

• getTags – Alle Tags in der Sammlung abrufen (zuerst verwenden, um Duplikate zu vermeiden)
• addTags – Durch Leerzeichen getrennte Tags zu angegebenen Notizen hinzufügen
• removeTags – Durch Leerzeichen getrennte Tags von angegebenen Notizen entfernen
• replaceTags – Ein Tag über angegebene Notizen hinweg umbenennen
• clearUnusedTags – Verwaiste Tags entfernen, die von keiner Notiz verwendet werden (destruktiv)

Medien-Verwaltung

• getMediaFilesNames – Mediendateien in collection.media auflisten, optional nach Muster gefiltert
• retrieveMediaFile – Eine Mediendatei als Base64-Inhalt herunterladen
• storeMediaFile – Medien aus Base64-Daten, einem absoluten Dateipfad oder einer URL hochladen
• deleteMediaFile – Eine Mediendatei aus collection.media entfernen (destruktiv)

💡 Beste Praxis für Bilder:

• ✅ Dateipfade verwenden (z. B. /Users/you/image.png) – Schnell und effizient
• ✅ URLs verwenden (z. B. https://example.com/image.jpg) – Direkter Download
• ❌ Base64 vermeiden – Extrem langsam und token-ineffizient

Sagen Sie Claude einfach, wo das Bild ist, und es wird den Upload automatisch mit der effizientesten Methode übernehmen.

Modell-/Vorlagen-Verwaltung

• modelNames – Alle verfügbaren Notiztypen/Modelle auflisten
• modelFieldNames – Feldnamen für einen bestimmten Notiztyp abrufen
• modelStyling – CSS-Formatierungsinformationen für einen Notiztyp abrufen
• modelTemplates – Die Kartenvorlagen (Vorder- und Rückseiten-HTML) für einen Notiztyp abrufen
• createModel – Einen neuen Notiztyp mit benutzerdefinierten Feldern, Kartenvorlagen und CSS erstellen (z. B. RTL-Modelle)
• updateModelStyling – Die CSS-Formatierung für einen vorhandenen Notiztyp aktualisieren (gilt für alle seine Karten)
• updateModelTemplates – Die Kartenvorlagen (Vorder- und Rückseiten-HTML) für einen vorhandenen Notiztyp aktualisieren (gilt für alle seine Karten)
• addModelField – Ein neues Feld zu einem vorhandenen Notiztyp hinzufügen (am Ende angehängt oder an einer bestimmten Position eingefügt)
• removeModelField – Ein Feld aus einem vorhandenen Notiztyp entfernen (löscht seinen Inhalt aus allen Notizen; erfordert ausdrückliche Bestätigung)
• renameModelField – Ein Feld in einem vorhandenen Notiztyp umbenennen (Kartenvorlagen, die den alten Namen referenzieren, müssen separat aktualisiert werden)
• repositionModelField – Die Position eines Feldes innerhalb eines vorhandenen Notiztyps ändern

Statistiken

• collection_stats – Aggregierte Statistiken über alle Decks mit Aufschlüsselung pro Deck und sammlungsweiten Kartenstatus-Zählungen
• review_stats – Analyse des Wiederholungsverlaufs (zeitliche Muster, Behaltensmetriken, Lernserien)

GUI-Tools

Tools, die die Anki-Desktop-Oberfläche steuern. Für Notizbearbeitungs-/Erstellungs- und Deck-Verwaltungsworkflows gedacht, nicht für Wiederholungssitzungen.

• guiBrowse – Den Karten-Browser öffnen und nach Karten suchen
• guiSelectCard – Eine bestimmte Karte im Karten-Browser auswählen
• guiSelectedNotes – IDs der aktuell im Karten-Browser ausgewählten Notizen abrufen
• guiAddCards – Den Dialog „Karten hinzufügen“ mit voreingestellten Notizdetails öffnen
• guiEditNote – Den Notiz-Editor für eine bestimmte Notiz öffnen
• guiDeckOverview – Den Deck-Übersichts-Dialog für ein bestimmtes Deck öffnen
• guiDeckBrowser – Den Deck-Browser-Dialog öffnen
• guiCurrentCard – Informationen zur aktuellen Karte im Wiederholungsmodus abrufen
• guiShowQuestion – Die Fragenseite der aktuellen Karte anzeigen
• guiShowAnswer – Die Antwortseite der aktuellen Karte anzeigen
• guiUndo – Die letzte Aktion in Anki rückgängig machen

Voraussetzungen

• Anki mit installiertem AnkiConnect-Plugin
• Node.js 22.12.0+

Installation

Es gibt mehrere Möglichkeiten, den Server auf Ihrem Rechner zu installieren. Nach der Installation gehen Sie zu Verbinden eines KI-Clients, um ihn mit Ihrem KI-Assistenten zu verbinden – lokal oder remote.

npm (global oder npx)

Der allgemeine Weg zur Installation des Servers, geeignet für jeden MCP-Client, der ihn direkt startet.

Installieren Sie ihn global für Clients, die den ankimcp-Befehl ausführen:

npm install -g @ankimcp/anki-mcp-server

Oder führen Sie ihn bei Bedarf ohne Installation aus:

npx @ankimcp/anki-mcp-server

MCPB-Bundle (Empfohlen für Claude Desktop)

Der einfachste Weg, diesen MCP-Server für Claude Desktop zu installieren:

1. Laden Sie das neueste .mcpb-Bundle von der Releases-Seite herunter
2. Installieren Sie die Erweiterung in Claude Desktop:
   • Methode 1: Gehen Sie zu Einstellungen → Erweiterungen und ziehen Sie die .mcpb-Datei per Drag & Drop hinein
   • Methode 2: Gehen Sie zu Einstellungen → Entwickler → Erweiterungen → Erweiterung installieren und wählen Sie dann die .mcpb-Datei aus
3. Konfigurieren Sie die AnkiConnect-URL bei Bedarf (Standard ist http://localhost:8765)
4. Starten Sie Claude Desktop neu

Das war's! Das Bundle enthält alles, was zum lokalen Ausführen des Servers benötigt wird.

Für Prüfer des Anthropic MCP-Verzeichnisses: Eine Schritt-für-Schritt-Anleitung von Null bis Integration mit einem vorab befüllten Beispiel-Deck finden Sie in docs/reviewer-setup.md.

Aus dem Quellcode installieren (für Entwicklung)

Für Entwicklung oder fortgeschrittene Nutzung (die Ausführung der Testsuite erfordert Node.js 24.9+ – die npm-Testskripte laden die ESM-only NestJS 12-Pakete über require(esm), was Jest nur dort unterstützt; die Laufzeitanforderung für die Nutzung des Servers bleibt 22.12.0+):

npm install
npm run build

Verbinden eines KI-Clients

Es gibt zwei Möglichkeiten, wie ein KI-Assistent diesen Server erreichen kann, abhängig davon, wo der Assistent läuft:

• Lokal – Der Server läuft auf demselben Rechner wie der KI-Client (Claude Desktop, Cursor, Cline, Zed oder eine lokale Browser-Sitzung). Verwenden Sie STDIO für Desktop-MCP-Clients, HTTP für lokale webbasierte Tools.
• Remote – Eine gehostete/remote KI (z. B. ChatGPT oder Claude.ai in der Cloud) muss das auf Ihrem lokalen Rechner laufende Anki erreichen. Verwenden Sie den verwalteten Tunnel (✅ empfohlen – authentifiziert) oder, als leichtere nicht authentifizierte Alternative, ngrok.

Lokal

Der Server läuft auf demselben Computer wie Ihr KI-Client und kommuniziert mit AnkiConnect auf localhost.

STDIO (primäre lokale Integration)

STDIO ist der Standard-Transport für lokale Desktop-MCP-Clients – Claude Desktop, Cursor IDE, Cline, Zed Editor und andere. Der Client startet den Server als Unterprozess und kommuniziert über Standard-Eingabe/-Ausgabe. Unterstützte Clients:

• Claude Desktop
• Cursor IDE – KI-gestützter Code-Editor
• Cline – VS-Code-Erweiterung für KI-Unterstützung
• Zed Editor – Schneller, moderner Code-Editor
• Andere MCP-Clients, die STDIO-Transport unterstützen

Für Claude Desktop ist das MCPB-Bundle der einfachste Weg. Für andere Clients konfigurieren Sie das npm-Paket mit dem --stdio-Flag.

Konfiguration – Wählen Sie eine Methode:

Methode 1: Mit npx (empfohlen – keine Installation erforderlich)

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Methode 2: Mit globaler Installation

Installieren Sie zunächst global:

npm install -g @ankimcp/anki-mcp-server

Konfigurieren Sie dann:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Speicherorte der Konfigurationsdateien:

• Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) oder %USERPROFILE%\.cursor\mcp.json (Windows)
• Cline: Über die Einstellungen-Benutzeroberfläche in VS Code zugänglich
• Zed Editor: Als MCP-Erweiterung über den Erweiterungs-Marketplace installieren

Für clientspezifische Funktionen und Fehlerbehebung konsultieren Sie die Dokumentation Ihres MCP-Clients. Siehe auch Mit Claude Desktop verbinden für eine Konfiguration, die direkt auf ein gebautes dist/main-stdio.js verweist.

HTTP (lokales webbasiertes KI)

Der HTTP-Modus führt den Server als lokalen Webserver aus, der das MCP-Streamable-HTTP-Protokoll spricht. Es ist der Transport, mit dem ein webbasiertes KI-Tool spricht, wenn es auf Ihren Rechner zeigt, und es ist auch das, was die Remote-Optionen der Außenwelt zugänglich machen. Für sich allein genommen bindet der HTTP-Modus nur an localhost.

Über localhost hinaus binden? Wenn Sie --host 0.0.0.0 übergeben (oder hinter einem Reverse-Proxy/einer öffentlichen Domain ausführen), akzeptiert der Server standardmäßig nur Loopback-Host-Header zum Schutz vor DNS-Rebinding – setzen Sie ALLOWED_HOSTS auf den/die Hostnamen, die Clients verwenden. Siehe HTTP-Modus-Konfiguration.

Einrichtung – Wählen Sie eine Methode:

Methode 1: Mit npx (empfohlen – keine Installation erforderlich)

# Quick start
npx @ankimcp/anki-mcp-server

# With custom options
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765

Methode 2: Mit globaler Installation

# Install once
npm install -g @ankimcp/anki-mcp-server

# Run the server
ankimcp

# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765

Methode 3: Aus dem Quellcode installieren (für die Entwicklung)

npm install
npm run build
npm run start:prod:http

Um einen lokalen HTTP-Server für ein cloudgehostetes KI erreichbar zu machen, verwenden Sie eine der Remote-Optionen unten.

Remote

Ein gehostetes/Remote-KI (z. B. ChatGPT oder Claude.ai in der Cloud) kann localhost nicht direkt erreichen. Diese Optionen machen Ihr lokales Anki im Internet zugänglich, sodass ein Remote-Assistent damit sprechen kann.

Tunnel (✅ Empfohlen)

Empfohlener Remote-Pfad – authentifiziert & sicher. Anders als ein roher öffentlicher Port erfordert der Tunnelmodus, dass Sie sich anmelden (OAuth-2.0-Gerätefluss), sodass der Endpunkt nicht für jeden offen ist, der die URL errät.

Der Tunnelmodus ermöglicht webbasierten KI-Assistenten, Ihr lokales Anki zu erreichen, ohne einen eigenen Tunnel auszuführen. Der Server verbindet sich über einen WebSocket mit dem verwalteten AnkiMCP-Tunneldienst (wss://tunnel.ankimcp.ai) und erhält eine öffentliche URL. Die Authentifizierung ist integriert – kein ngrok-Konto oder separater Tunnelprozess erforderlich, und Sie melden sich einmal an.

Anmelden (OAuth-Gerätefluss):

Der Tunnelmodus verwendet das OAuth-2.0-Geräteautorisierungs-Grant. Beim Anmelden öffnet sich Ihr Browser automatisch auf einer Genehmigungsseite, wobei der Code bereits in der URL eingebettet ist – nichts zum Tippen, nur genehmigen. (Wenn der Browser nicht geöffnet werden kann, gibt das Terminal als Fallback eine Verifizierungs-URL und einen Code zur manuellen Eingabe aus.) Bei Erfolg werden die Anmeldeinformationen in ~/.ankimcp/credentials.json gespeichert (Dateiberechtigungen 0600).

# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
ankimcp --login
npx @ankimcp/anki-mcp-server --login

# Clear saved credentials
ankimcp --logout

Tunnel starten:

# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
ankimcp --tunnel
npx @ankimcp/anki-mcp-server --tunnel

# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
ankimcp --tunnel wss://my-tunnel.example.com

Wenn keine Anmeldeinformationen vorhanden sind, startet --tunnel automatisch zuerst den Anmeldevorgang und fährt dann mit dem Tunnel fort. Diese automatische Anmeldung erfordert ein interaktives Terminal – wenn stdout kein TTY ist (systemd, headless Docker, CI), schlägt der Server schnell fehl und fordert Sie auf, zuerst ankimcp --login auszuführen. Sobald die Verbindung hergestellt ist, wird die öffentliche Tunnel-URL ausgegeben; drücken Sie Strg+C, um die Verbindung zu trennen. Teilen Sie diese URL mit Ihrem KI-Assistenten.

Umgebungsvariablen des Tunnelmodus:

Variable	Beschreibung	Standard
TUNNEL_SERVER_URL	Tunnel-Server-WebSocket-URL (der --tunnel/--login-Flagwert überschreibt dies)	wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_ID	OAuth-Client-ID für den Gerätefluss. Erweitert – nur erforderlich, wenn auf einen selbst gehosteten Tunnel-/Auth-Dienst verwiesen wird.	(integriert)

Die Gerätefluss-Auth-Endpunkte (/auth/device, /auth/token) werden von TUNNEL_SERVER_URL abgeleitet. Wenn Sie also --tunnel (oder TUNNEL_SERVER_URL) auf einen anderen Host ausrichten, wird auch die Authentifizierung auf diesen Host verlagert.

So funktioniert es: Der Tunnelmodus führt den MCP-Server prozessintern hinter einem In-Memory-Transport (TunnelTransport) aus. Dieser Transport besitzt den MCP-Server und wandelt jeden weitergeleiteten Anforderungstext in eine Antwort um, und TunnelClient verbindet ihn über einen WebSocket mit dem Remote-Tunneldienst – MCP-Anforderungen werden hinein- und Antworten herausgeleitet. AnkiConnect wird weiterhin nur auf Ihrem lokalen Rechner erreicht.

Protokollrevisionen: Da der Tunnel den MCP-Server prozessintern verbindet, bedient der Tunnelmodus nur die 2025er-Revision des MCP-Protokolls, während STDIO- und HTTP-Modi sowohl 2025 als auch die neuere 2026-07-28-Revision bedienen. Jedes Tool verhält sich in beiden Fällen gleich – aber ein Client, der nur 2026-07-28 spricht, wird über den Tunnel mit einem Protokollversionsfehler abgewiesen; führen Sie für diesen Client den STDIO- oder HTTP-Modus aus.

ngrok (unauthentifizierte Alternative)

Wenn Sie den lokalen HTTP-Modus lieber öffentlich zugänglich machen möchten, ohne ein Konto beim verwalteten Tunnel zu haben, startet das integrierte --ngrok-Flag einen ngrok-Unterprozess (src/services/ngrok.service.ts) und gibt die öffentliche URL im Startbanner aus:

# One-time ngrok setup, then:
ankimcp --ngrok

Diese Route ist unauthentifiziert – jeder mit der URL kann Ihr Anki erreichen, daher ist sie weniger sicher als Tunnel. Bevorzugen Sie Tunnel, es sei denn, Sie haben einen bestimmten Grund, Ihren eigenen ngrok-Endpunkt zu verwalten. (Erfordert eine globale ngrok-Installation und ein Authtoken.)

Das --ngrok-Flag startet ngrok mit --host-header=rewrite, sodass ngrok das vorgelagerte Host zu localhost umschreibt, bevor es weiterleitet. Dadurch bleiben Anforderungen innerhalb der Loopback-Host-Zulassungsliste (siehe DNS-Rebinding-Schutz), ohne dass Sie die öffentliche *.ngrok-Domain zu ALLOWED_HOSTS hinzufügen müssen. Wenn Sie ngrok stattdessen manuell ausführen, verwenden Sie dasselbe Flag – ngrok http --host-header=rewrite 3000 – andernfalls leitet ngrok den öffentlichen ngrok-Hostnamen als Host weiter und der Server lehnt ihn mit 403 ab.

CLI-Optionen (alle Modi)

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -p, --port <number>            Port to listen on (HTTP mode; default: 3000, or PORT env var)
  -h, --host <address>           Host to bind to (HTTP mode; default: 127.0.0.1, or HOST env var)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765, or ANKI_CONNECT_URL env var)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks all write operations)
  --help                         Show help message

Usage with npx (no installation needed):
  npx @ankimcp/anki-mcp-server                        # HTTP mode
  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
  npx @ankimcp/anki-mcp-server --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

Usage with global installation:
  npm install -g @ankimcp/anki-mcp-server             # Install once
  ankimcp                                             # HTTP mode
  ankimcp --port 8080                                 # Custom port
  ankimcp --stdio                                     # STDIO mode
  ankimcp --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

Schreibgeschützter Modus (alle Modi)

Das --read-only-Flag verhindert alle Änderungen an Ihrer Anki-Sammlung. Wenn aktiviert:

• Alle Leseoperationen funktionieren normal (Decks durchsuchen, Karten anzeigen, Notizen suchen)
• Wiederholungsoperationen sind erlaubt (Sync, answerCards, suspend/unsuspend)
• Inhaltsänderungen sind blockiert (addNote, deleteNotes, createDeck, updateNoteFields usw.)
• Nützlich zum sicheren Erkunden von Anki-Daten ohne Risiko versehentlicher Änderungen

# HTTP mode with read-only
ankimcp --read-only

# STDIO mode with read-only
ankimcp --stdio --read-only

# Can combine with other flags
ankimcp --ngrok --read-only

Sie können den schreibgeschützten Modus auch über eine Umgebungsvariable aktivieren:

READ_ONLY=true ankimcp

Oder in der MCP-Client-Konfiguration:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Mit Claude Desktop verbinden (lokaler Modus)

Sie können den Server in Claude Desktop konfigurieren, indem Sie entweder:

• Gehen Sie zu: Einstellungen → Entwickler → Konfiguration bearbeiten
• Oder bearbeiten Sie die Konfigurationsdatei manuell

Konfiguration

Fügen Sie Folgendes zu Ihrer Claude-Desktop-Konfiguration hinzu:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Ersetzen Sie /path/to/anki-mcp-server durch Ihren tatsächlichen Projektpfad.

Speicherorte der Konfigurationsdateien

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Weitere Details finden Sie in der offiziellen MCP-Dokumentation.

Umgebungsvariablen (optional)

Variable	Beschreibung	Standard
ANKI_CONNECT_URL	AnkiConnect-URL	http://localhost:8765
ANKI_CONNECT_API_VERSION	API-Version	6
ANKI_CONNECT_API_KEY	API-Schlüssel, falls in AnkiConnect konfiguriert	-
ANKI_CONNECT_TIMEOUT	Anforderungs-Timeout in ms	5000
READ_ONLY	Schreibgeschützten Modus aktivieren (true oder 1)	false
PORT	HTTP-Modus: Port zum Abhören (--port-Flag hat Vorrang)	3000
HOST	HTTP-Modus: Adresse zum Binden (--host-Flag hat Vorrang)	127.0.0.1
ALLOWED_HOSTS	HTTP-Modus: zusätzliche Host-Headerwerte, die über Loopback hinaus akzeptiert werden (kommagetrennte Hostnamen). Erforderlich beim Binden an eine LAN-/öffentliche Adresse oder beim Ausführen hinter einem Reverse-Proxy. Siehe HTTP-Modus-Konfiguration.	nur Loopback
ALLOWED_ORIGINS	HTTP-Modus: kommagetrennte Zulassungsliste von Browser-Origin/Referer-Mustern (Platzhalter unterstützt, z. B. https://*.ngrok.io).	http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URL	Tunnel-Server-WebSocket-URL (nur Tunnelmodus)	wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPES	Zusätzliche MIME-Typen für Dateipfadimporte (kommagetrennt, z. B. application/pdf)	-
MEDIA_IMPORT_DIR	Dateipfadimporte auf dieses Verzeichnis beschränken	-
MEDIA_ALLOWED_HOSTS	Bestimmte private Netzwerk-Hosts für URL-Importe zulassen (kommagetrennt, z. B. 192.168.1.50,my-nas)	-

Verwendungsbeispiele

Notizen suchen und aktualisieren

# Search for notes in a specific deck
findNotes(query: "deck:Spanish")

# Get detailed information about notes
notesInfo(notes: [1234567890, 1234567891])

# Update a note's fields (HTML content supported)
updateNoteFields(note: {
  id: 1234567890,
  fields: {
    "Front": "<b>¿Cómo estás?</b>",
    "Back": "How are you?"
  }
})

# Delete notes (requires confirmation)
deleteNotes(notes: [1234567890], confirmDeletion: true)

Beispiele für die Anki-Abfragesyntax

Das findNotes-Tool unterstützt die leistungsstarke Abfragesyntax von Anki:

• "deck:DeckName" – Alle Notizen in einem bestimmten Deck
• "tag:important" – Notizen mit dem Tag „important“
• "is:due" – Karten, die zur Wiederholung fällig sind
• "is:new" – Neue Karten, die noch nicht gelernt wurden
• "added:7" – Notizen, die in den letzten 7 Tagen hinzugefügt wurden
• "front:hello" – Notizen mit „hello“ im Vorderfeld
• "flag:1" – Notizen mit roter Flagge
• "prop:due<=2" – Karten, die innerhalb von 2 Tagen fällig sind
• "deck:Spanish tag:verb" – Spanisch-Deck-Notizen mit Verb-Tag (UND)
• "deck:Spanish OR deck:French" – Notizen aus beiden Decks

Wichtige Hinweise

CSS- und HTML-Behandlung

• Das notesInfo-Tool gibt CSS-Formatierungsinformationen für ein ordnungsgemäßes Rendering-Bewusstsein zurück
• Das updateNoteFields-Tool unterstützt HTML-Inhalte in Feldern und bewahrt die CSS-Formatierung
• Jedes Notizmodell hat seine eigene CSS-Formatierung – verwenden Sie modelStyling, um modellspezifisches CSS zu erhalten

Aktualisierungswarnung

⚠️ WICHTIG: Wenn Sie updateNoteFields verwenden, betrachten Sie die Notiz NICHT im Anki-Browser während der Aktualisierung, da die Felder sonst nicht ordnungsgemäß aktualisiert werden. Schließen Sie den Browser oder wechseln Sie vor der Aktualisierung zu einer anderen Notiz. Siehe Bekannte Probleme für weitere Details.

Löschsicherheit

Das deleteNotes-Tool erfordert eine explizite Bestätigung (confirmDeletion: true), um versehentliche Löschungen zu verhindern. Das Löschen einer Notiz entfernt ALLE zugehörigen Karten dauerhaft.

Sicherheit

Validierung von Mediendateipfaden und URLs

Die Medien-Tools (storeMediaFile, retrieveMediaFile, deleteMediaFile) und updateNoteFields-Audio-/Bildfelder enthalten Sicherheitsvalidierungen, um Missbrauch durch Prompt-Injection zu verhindern:

• Dateipfadimporte sind nur auf Mediendateitypen beschränkt (Bilder, Audio, Video). Nicht-Medien-Dateien (z. B. SSH-Schlüssel, Anmeldeinformationen, Shell-Konfigurationen) werden basierend auf dem MIME-Typ abgelehnt. Konfigurieren Sie MEDIA_ALLOWED_TYPES, um zusätzliche Dateitypen zuzulassen, oder MEDIA_IMPORT_DIR, um Importe auf ein bestimmtes Verzeichnis zu beschränken.
• URL-Importe werden gegen SSRF-Angriffe validiert. Anforderungen an private Netzwerke (10.x, 172.16.x, 192.168.x), Loopback (127.x), link-lokale (169.254.x) und Nicht-HTTP(S)-Schemata werden blockiert. Konfigurieren Sie MEDIA_ALLOWED_HOSTS, um bestimmte private Netzwerk-Hosts zuzulassen.
• Dateinamen werden bereinigt, um Pfad-Traversal zu verhindern (z. B. werden ../../-Sequenzen entfernt).

Diese Schutzmaßnahmen gelten für storeMediaFile, retrieveMediaFile, deleteMediaFile und updateNoteFields-Audio-/Bildfelder.

Pfad-Traversal-Schwachstelle gemeldet von Hideaki Takahashi.

DNS-Rebinding-Schutz (HTTP-Transport)

Wenn der Server im HTTP-Modus läuft, validiert er den Host-Header bei jeder Anfrage. Standardmäßig werden nur Loopback-Hosts (localhost, 127.0.0.1, ::1) akzeptiert, unabhängig vom Port. Host ist ein im Browser verbotener Header, sodass eine bösartige Webseite ihn nicht fälschen kann – dies schließt den DNS-Rebinding-Pfad, bei dem eine umgeleitete Seite den lokalen Server mit einem gefälschten Host und ohne Origin erreicht und auf die MCP-Tools zugreift. Ein nicht erlaubter Host wird mit 403 abgelehnt.

Wenn Sie an 0.0.0.0 binden, hinter einem Reverse-Proxy laufen oder eine öffentliche Tunnel-Domain freigeben, setzen Sie ALLOWED_HOSTS (kommagetrennte Hostnamen), um diese Hosts zuzulassen. Bei Tunneling mit ngrok verwendet der Server --host-header=rewrite, sodass der Upstream weiterhin einen Loopback-Host sieht. Siehe HTTP-Modus-Konfiguration für die vollständige Liste der Optionen.

DNS-Rebinding-Schwachstelle gemeldet von avishaigo-commits und yotampe-pluto.

Datenschutzerklärung

Dieser MCP-Server läuft lokal auf Ihrem Rechner und erhebt keine Telemetrie-, Analyse- oder Nutzungsdaten.

Vollständige Richtlinie: https://ankimcp.ai/privacy/

• Datenerhebung: Der Server erhebt nichts. Er leitet Anfragen zwischen Ihrem KI-Assistenten und Ihrem lokalen AnkiConnect-Plugin weiter.
• Nutzung / Speicherung: Keine serverseitige Speicherung. Alle Karteikartendaten verbleiben in Ihrer Anki-Installation auf Ihrem eigenen Gerät.
• Weitergabe an Dritte: Keine. Der Server kommuniziert nur mit der von Ihnen konfigurierten AnkiConnect-URL (Standard: localhost). Wenn Sie Ankis integrierte AnkiWeb-Synchronisierung aktivieren, erfolgt diese direkt zwischen Ihrer Anki-Installation und AnkiWeb – außerhalb des Zuständigkeitsbereichs dieses Servers.
• Aufbewahrung: Nicht zutreffend – es werden keine Daten serverseitig aufbewahrt.
• Kontakt: support@ankimcp.ai

Bekannte Probleme

Eine umfassende Liste bekannter Probleme und Einschränkungen finden Sie in unserer Dokumentation:

Dokumentation zu bekannten Problemen

Kritische Einschränkungen

Notizaktualisierungen schlagen im Browser fehl

⚠️ WICHTIG: Bei der Aktualisierung von Notizen mit updateNoteFields schlägt die Aktualisierung still fehl, wenn die Notiz gerade im Browserfenster von Anki angezeigt wird. Dies ist eine Einschränkung von AnkiConnect (Upstream).

Workaround: Schließen Sie den Browser immer oder navigieren Sie zu einer anderen Notiz, bevor Sie aktualisieren.

Weitere Details und andere bekannte Probleme finden Sie in der vollständigen Dokumentation.

Fehlerbehebung

ERR_REQUIRE_ESM-Fehler

Wenn Sie einen Fehler wie diesen sehen:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Bedeutet dies, dass Ihre Node.js-Version nicht unterstützt wird. Der Server erfordert Node.js 22.12.0+.

Hinweis: Die minimale unterstützte Laufzeit ist Node.js 22.12.0. Node.js 20 (Iron) hat am 30.04.2026 das Ende seiner Lebensdauer erreicht und wird nicht mehr unterstützt.

Überprüfen Sie Ihre Version:

node --version

Lösung: Aktualisieren Sie Node.js auf Version 22.12.0+. Sie können es von nodejs.org herunterladen oder einen Versionsmanager wie nvm verwenden.

Entwicklung

Transportmodi

Dieser Server unterstützt drei MCP-Transportmodi über separate Einstiegspunkte:

STDIO-Modus (Standard)

• Für lokale MCP-Clients wie Claude Desktop
• Verwendet Standard-Eingabe/Ausgabe für die Kommunikation
• Einstiegspunkt: dist/main-stdio.js
• Ausführen: npm run start:prod:stdio oder node dist/main-stdio.js
• MCPB-Bundle: Verwendet den STDIO-Modus

HTTP-Modus (Streamable HTTP)

• Für entfernte MCP-Clients und webbasierte Integrationen
• Verwendet das MCP-Streamable-HTTP-Protokoll
• Einstiegspunkt: dist/main-http.js
• Ausführen: npm run start:prod:http oder node dist/main-http.js
• Standardport: 3000 (konfigurierbar über die Umgebungsvariable PORT)
• Standardhost: 127.0.0.1 (konfigurierbar über die Umgebungsvariable HOST)
• MCP-Endpunkt: http://127.0.0.1:3000/ (Root-Pfad)

Tunnel-Modus (Verwalteter WebSocket-Tunnel)

• Für webbasierte KI-Assistenten über den verwalteten AnkiMCP-Tunneldienst mit integrierter Authentifizierung
• Der MCP-Server läuft prozessintern hinter einem In-Memory-Transport; TunnelTransport besitzt den MCP-Server und TunnelClient verbindet ihn über einen WebSocket mit dem Tunneldienst
• Protokoll: Bedient nur die 2025er-MCP-Revision (STDIO und HTTP bedienen auch 2026-07-28)
• Einstiegspunkt: dist/main-tunnel.js
• Ausführen: node dist/main-tunnel.js --tunnel (oder ankimcp --tunnel)
• Authentifizierung: ankimcp --login / ankimcp --logout; Anmeldedaten gespeichert unter ~/.ankimcp/credentials.json (0600)
• Entwicklung: npm run start:dev:tunnel (Watch-Modus, führt --tunnel --debug aus)

Erstellen

npm run build  # Builds once, creates dist/ with all three entry points

main-stdio.js, main-http.js und main-tunnel.js werden alle in dasselbe dist/-Verzeichnis gebaut. Wählen Sie je nach Bedarf, welches Sie ausführen.

HTTP-Modus-Konfiguration

Umgebungsvariablen:

• PORT – HTTP-Serverport (Standard: 3000)
• HOST – Bind-Adresse (Standard: 127.0.0.1 für Nur-Localhost)
• ALLOWED_HOSTS – Kommagetrennte zusätzliche Host-Headerwerte, die über den integrierten Loopback-Satz hinaus akzeptiert werden (localhost, 127.0.0.1, ::1). Nur Hostname und portunabhängig. Standard: nur Loopback.
• ALLOWED_ORIGINS – Kommagetrennte Allowlist von Browser-Origin/Referer-Mustern; Wildcards werden unterstützt (z. B. https://*.ngrok.io). Standard: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
• LOG_LEVEL – Protokollierungsstufe (Standard: info)

Sicherheit:

• Host-Header-Validierung (DNS-Rebinding-Schutz) – jede HTTP-Anfrage muss einen Host-Header tragen, der der Allowlist entspricht. Standardmäßig werden nur Loopback-Hosts (localhost, 127.0.0.1, ::1) akzeptiert, unabhängig vom Port. Host ist ein im Browser verbotener Header, sodass eine bösartige Webseite ihn nicht fälschen kann – dies schließt den DNS-Rebinding-Pfad, bei dem eine umgeleitete Seite den Server mit einem gefälschten Host und ohne Origin erreicht. Ein nicht erlaubter Host wird mit 403 abgelehnt.
• Origin-Header-Validierung – Browseranfragen mit einem vorhandenen, aber nicht erlaubten Origin/Referer werden abgelehnt. Anfragen ohne Origin (curl, Postman, MCP-over-HTTP-Clients) sind erlaubt; die Host-Validierung ist die Verteidigung gegen Rebinding.
• Bindet standardmäßig an localhost (127.0.0.1).
• Keine Authentifizierung in der aktuellen Version (OAuth-Unterstützung geplant).

HTTP-Modus über localhost hinaus freigeben – wenn Sie an eine LAN-/öffentliche Adresse binden oder den Server hinter einem Reverse-Proxy oder einer öffentlichen Domain betreiben, müssen Sie ALLOWED_HOSTS auf den/die Hostnamen setzen, die Clients verwenden werden, andernfalls wird jede Nicht-Loopback-Anfrage mit 403 abgelehnt:

# Bind to all interfaces and accept the machine's LAN name + a public domain
ALLOWED_HOSTS=my-nas.local,anki.example.com PORT=8080 HOST=0.0.0.0 node dist/main-http.js

Wenn Sie an 0.0.0.0/:: ohne ALLOWED_HOSTS binden, protokolliert der Server eine Startwarnung, dass nur Loopback-Host-Header akzeptiert werden.

Docker / Reverse-Proxy / öffentliche Domain: dieselbe Regel gilt. In Docker kommen Anfragen normalerweise mit dem veröffentlichten Hostnamen des Containers oder dem Host des Proxys an, also setzen Sie ALLOWED_HOSTS entsprechend. Ein Reverse-Proxy (nginx, Caddy, Traefik) sollte entweder den ursprünglichen Host weiterleiten und diesen Hostnamen in ALLOWED_HOSTS auflisten oder den Upstream-Host auf localhost umschreiben. Die integrierte --ngrok-Integration übernimmt dies automatisch (siehe unten).

Beispiel: Ausführungsmodi

# Development - STDIO mode (watch mode with auto-rebuild)
npm run start:dev:stdio

# Development - HTTP mode (watch mode with auto-rebuild)
npm run start:dev:http

# Production - STDIO mode
npm run start:prod:stdio
# or
node dist/main-stdio.js

# Production - HTTP mode
npm run start:prod:http
# or
PORT=8080 HOST=0.0.0.0 node dist/main-http.js

Erstellen eines MCPB-Bundles

Um ein verteilbares MCPB-Bundle zu erstellen:

npm run mcpb:bundle

Dieser Befehl wird:

1. Version von package.json auf manifest.json synchronisieren
2. Alte .mcpb-Dateien entfernen
3. Das TypeScript-Projekt erstellen
4. dist/ und node_modules/ in eine .mcpb-Datei packen
5. mcpb clean ausführen, um devDependencies zu entfernen (optimiert das Bundle von ~47 MB auf ~10 MB)

Die Ausgabedatei wird anki-mcp-server-X.X.X.mcpb heißen und für die Ein-Klick-Installation verteilt werden können.

Was gebündelt wird

Das MCPB-Bundle enthält:

• Kompiliertes JavaScript (dist/-Verzeichnis – enthält alle drei Einstiegspunkte)
• Nur Produktionsabhängigkeiten (node_modules/ – devDependencies entfernt durch mcpb clean)
• Paketmetadaten (package.json)
• Manifest-Konfiguration (manifest.json – konfiguriert für die Verwendung von main-stdio.js)
• Symbol (icon.png)

Quelldateien, Tests und Entwicklungskonfigurationen werden automatisch über .mcpbignore ausgeschlossen.

Protokollierung in Claude Desktop

Wenn als MCPB-Erweiterung in Claude Desktop ausgeführt, werden Protokolle geschrieben an:

Protokollspeicherort: ~/Library/Logs/Claude/ (macOS)

Die Protokolle sind auf mehrere Dateien aufgeteilt:

• main.log – Allgemeine Claude-Desktop-Anwendungsprotokolle
• mcp-server-Anki MCP Server.log – MCP-Protokollnachrichten für diese Erweiterung
• mcp.log – Kombinierte MCP-Protokolle aller Server

Hinweis: Die pino-Protokollausgabe (INFO-, ERROR-, WARN-Meldungen aus dem Servercode) geht an stderr und erscheint in den MCP-spezifischen Protokolldateien. Claude Desktop bestimmt, welche Protokolldatei welche Meldungen erhält, aber im Allgemeinen:

• Anwendungsstart und MCP-Protokollkommunikation → MCP-spezifisches Protokoll
• Interne Serverprotokollierung (pino) → Sowohl MCP-spezifisches Protokoll als auch manchmal main.log

Um Protokolle in Echtzeit anzuzeigen:

tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log

Debuggen des MCP-Servers

Sie können den MCP-Server mit dem MCP-Inspector debuggen und einen Debugger aus Ihrer IDE (WebStorm, VS Code usw.) anhängen.

Hinweis für den HTTP-Modus: Wenn Sie den HTTP-Modus (Streamable HTTP) mit dem MCP-Inspector testen, verwenden Sie „Verbindungstyp: Über Proxy", um CORS-Fehler zu vermeiden.

Schritt 1: Debug-Server im MCP-Inspector konfigurieren

Der mcp-inspector-config.json enthält bereits eine Debug-Server-Konfiguration:

{
  "mcpServers": {
    "stdio-server-debug": {
      "type": "stdio",
      "command": "node",
      "args": ["--inspect-brk=9229", "dist/main-stdio.js"],
      "env": {
        "MCP_SERVER_NAME": "anki-mcp-stdio-debug",
        "MCP_SERVER_VERSION": "1.0.0",
        "LOG_LEVEL": "debug"
      },
      "note": "Anki MCP server with debugging enabled on port 9229"
    }
  }
}

Schritt 2: Debug-Server starten

Führen Sie den MCP-Inspector mit dem Debug-Server aus:

npm run inspector:debug

Dies startet den Server mit aktiviertem Node.js-Debugging auf Port 9229 und pausiert die Ausführung in der ersten Zeile.

Schritt 3: Debugger aus Ihrer IDE anhängen

WebStorm

1. Gehen Sie zu Ausführen → Konfigurationen bearbeiten
2. Fügen Sie eine neue An Node.js/Chrome anhängen-Konfiguration hinzu
3. Setzen Sie den Port auf 9229
4. Klicken Sie auf Debuggen, um anzuhängen

VS Code

1. Öffnen Sie das Debug-Panel (Strg+Umschalt+D / Cmd+Umschalt+D)
2. Wählen Sie die Konfiguration Debug MCP Server (Attach)
3. Drücken Sie F5, um anzuhängen

Schritt 4: Haltepunkte setzen und debuggen

Sobald angehängt, können Sie:

• Haltepunkte in Ihren TypeScript-Quelldateien setzen
• Die Codeausführung schrittweise durchgehen
• Variablen und Aufrufstapel untersuchen
• Die Debug-Konsole zum Auswerten von Ausdrücken verwenden

Der Debugger arbeitet mit Source Maps, sodass Sie den ursprünglichen TypeScript-Code debuggen können, anstatt des kompilierten JavaScripts.

Debuggen mit Claude Desktop

Sie können den MCP-Server auch debuggen, während er in Claude Desktop läuft, indem Sie den Node.js-Debugger aktivieren und Ihre IDE anhängen.

Schritt 1: Claude Desktop für das Debugging konfigurieren

Aktualisieren Sie Ihre Claude-Desktop-Konfiguration, um das Debugging zu aktivieren:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": [
        "--inspect=9229",
        "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
      ],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Wesentliche Änderung: Fügen Sie --inspect=9229 vor dem Pfad zu dist/main-stdio.js hinzu

Debug-Optionen:

• --inspect=9229 – Debugger sofort starten, blockiert nicht (empfohlen)
• --inspect-brk=9229 – Ausführung pausieren, bis der Debugger anhängt (zum Debuggen von Startproblemen)

Schritt 2: Claude Desktop neu starten

Nach dem Speichern der Konfiguration starten Sie Claude Desktop neu. Der MCP-Server läuft jetzt mit aktiviertem Debugging auf Port 9229.

Schritt 3: Debugger aus Ihrer IDE anhängen

WebStorm

1. Gehen Sie zu Ausführen → Konfigurationen bearbeiten
2. Klicken Sie auf die Schaltfläche + und wählen Sie An Node.js/Chrome anhängen
3. Konfigurieren Sie:
   • Name: Attach to Anki MCP (Claude Desktop)
   • Host: localhost
   • Port: 9229
   • Anhängen an: Node.js < 8 oder Chrome or Node.js > 6.3 (je nach WebStorm-Version)
4. Klicken Sie auf OK
5. Klicken Sie auf Debuggen (Umschalt+F9), um anzuhängen

VS Code

1. Fügen Sie zu .vscode/launch.json hinzu:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Anki MCP (Claude Desktop)",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

2. Öffnen Sie das Debug-Panel (Strg+Umschalt+D / Cmd+Umschalt+D)
3. Wählen Sie Attach to Anki MCP (Claude Desktop)
4. Drücken Sie F5, um anzuhängen

Schritt 4: In Echtzeit debuggen

Sobald der Debugger angehängt ist, kannst du:

• Haltepunkte in deinen TypeScript-Quelldateien setzen (z. B. src/mcp/primitives/essential/tools/create-model.tool.ts)
• Claude Desktop normal verwenden – Haltepunkte werden ausgelöst, wenn Tools aufgerufen werden
• Die Codeausführung schrittweise durchgehen
• Variablen und Aufrufliste untersuchen
• Die Debug-Konsole verwenden

Beispiel: Setze einen Haltepunkt in create-model.tool.ts in Zeile 119 und bitte dann Claude, ein neues Modell zu erstellen. Der Debugger wird an deinem Haltepunkt anhalten!

Hinweis: Der Debugger bleibt angehängt, solange Claude Desktop läuft. Du kannst ihn jederzeit abhängen und wieder anhängen, ohne Claude Desktop neu zu starten.

Build-Befehle

npm run build              # Build the project (compile TypeScript to JavaScript)
npm run start:dev:stdio    # STDIO mode with watch (auto-rebuild)
npm run start:dev:http     # HTTP mode with watch (auto-rebuild)
npm run type-check         # Run TypeScript type checking
npm run lint               # Run ESLint
npm run mcpb:bundle        # Sync version, clean, build, and create MCPB bundle

NPM-Paket-Tests (lokal)

Teste das npm-Paket lokal, bevor du es veröffentlichst:

# 1. Create local package
npm run pack:local         # Builds and creates @ankimcp/anki-mcp-server-*.tgz

# 2. Install globally from local package
npm run install:local      # Installs from ./@ankimcp/anki-mcp-server-*.tgz

# 3. Test the command
ankimcp                    # Runs HTTP server on port 3000

# 4. Uninstall when done testing
npm run uninstall:local    # Removes global installation

So funktioniert es:

• npm pack erstellt eine .tgz-Datei, die identisch mit dem ist, was npm publish erstellen würde
• Die Installation von .tgz simuliert, was Benutzer von npm install -g ankimcp erhalten
• So kannst du die vollständige Benutzererfahrung testen, bevor du auf npm veröffentlichst

Testbefehle

npm test              # Run all tests
npm run test:unit     # Run unit tests only
npm run test:tools    # Run tool-specific tests
npm run test:workflows # Run workflow integration tests
npm run test:e2e      # Run end-to-end tests
npm run test:cov      # Run tests with coverage report
npm run test:watch    # Run tests in watch mode
npm run test:debug    # Run tests with debugger
npm run test:ci       # Run tests for CI (silent, with coverage)

Testabdeckung

Das Projekt hält Mindestschwellen von 70 % Abdeckung ein für:

• Branches
• Funktionen
• Zeilen
• Anweisungen

Abdeckungsberichte werden im Verzeichnis coverage/ erzeugt.

Versionierung

Dieses Projekt folgt Semantic Versioning mit einem Pre-1.0-Entwicklungsansatz:

• 0.x.x – Beta-/Entwicklungsversionen (aktuelle Phase)

  • 0.1.x – Fehlerbehebungen und Patches
  • 0.2.0+ – Neue Funktionen oder kleinere Verbesserungen
  • Breaking Changes sind in 0.x-Versionen zulässig

• 1.0.0 – Erste stabile Version

  • Wird veröffentlicht, wenn die API stabil und getestet ist
  • Breaking Changes erfordern größere Versionssprünge (2.0.0 usw.)

Aktueller Status: 0.22.0 – Aktive Beta-Entwicklung. Zu den jüngsten Funktionen gehören sammlungsweite Wiederholungsanalysen (review_stats aggregiert jetzt über alle Decks, wenn deck weggelassen wird), Modellfeldverwaltung (addModelField, removeModelField, renameModelField, repositionModelField), Batch-Notizerstellung (addNotes), integriertes ngrok-Tunneling (--ngrok-Flag), Medienverwaltung, Modell-/Vorlagenverwaltung und umfassende Deck-Statistiken. APIs können sich basierend auf Feedback und Tests ändern.

Entwicklung der MCPB-Spezifikation

Dieses Projekt zielt auf die MCPB-Bundle-Spezifikation von Anthropic ab, die sich noch in der Entwicklung befindet. Wir verfolgen die Spezifikation unter https://github.com/modelcontextprotocol/mcpb und können Breaking Changes einführen, um konform zu bleiben. Breaking Changes sind im 0.x.x-Versionierungsschema zulässig.

Ähnliche Projekte

Wenn du Anki-MCP-Integrationen erkundest, gibt es weitere Projekte in diesem Bereich:

scorzeth/anki-mcp-server

• Status: Scheint aufgegeben zu sein (keine aktuellen Updates)
• Frühe Implementierung der Anki-MCP-Integration

nailuoGG/anki-mcp-server

• Ansatz: Leichtgewichtige Einzeldatei-Implementierung
• Architektur: Prozedurale Codestruktur mit allen Tools in einer Datei
• Geeignet für: Einfache Anwendungsfälle, minimale Abhängigkeiten

Warum sich dieses Projekt unterscheidet:

• Unternehmensgerechte Architektur: Aufgebaut auf NestJS mit Dependency Injection
• Modulares Design: Jedes Tool ist eine separate Klasse mit klarer Trennung der Zuständigkeiten
• Wartbarkeit: Einfach um neue Funktionen erweiterbar, ohne bestehenden Code anzufassen
• Tests: Umfassende Testsuite mit 70 %-Abdeckungsanforderung
• Typsicherheit: Strenges TypeScript mit Zod-Validierung
• Fehlerbehandlung: Robuste Fehlerbehandlung mit hilfreichem Benutzerfeedback
• Produktionsreif: Ordentliche Protokollierung, Fortschrittsberichte und MCPB-Bundle-Unterstützung
• Skalierbarkeit: Kann leicht von grundlegenden Tools zu komplexen Workflows wachsen

Anwendungsfall: Wenn du eine solide Grundlage für den Aufbau fortgeschrittener Anki-Integrationen benötigst oder die Funktionalität erheblich erweitern möchtest, erleichtert der architektonische Ansatz dieses Projekts die Wartung und Skalierung im Laufe der Zeit.

Nützliche Links

• Model Context Protocol Dokumentation
• AnkiConnect-API-Dokumentation
• Claude Desktop Download
• Desktop-Erweiterungen erstellen (Anthropic-Blog)
• MCP-Server-Repository
• NestJS-Dokumentation
• Offizielle Anki-Website

Lizenz & Namensnennung

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe LICENSE für den vollständigen Text.

Copyright © 2026 Anatoly Tarnavsky.

Namensnennungen Dritter

• Anki® ist eine eingetragene Marke von Ankitects Pty Ltd. Dieses Projekt ist ein inoffizielles Drittanbieter-Tool und steht in keiner Verbindung zu Ankitects Pty Ltd, wird von diesem nicht unterstützt oder gesponsert. Das Anki-Logo wird unter der alternativen Lizenz zur Referenzierung von Anki mit einem Link zu https://apps.ankiweb.net verwendet. Für die offizielle Anki-Anwendung besuche https://apps.ankiweb.net.

• Model Context Protocol (MCP) ist ein offener Standard von Anthropic. Das MCP-Logo stammt aus dem offiziellen MCP-Dokumentationsrepository und wird unter der MIT-Lizenz verwendet. Weitere Informationen zu MCP findest du unter https://modelcontextprotocol.io.

• Dies ist ein unabhängiges Projekt, das Anki- und MCP-Technologien verbindet. Alle Marken, Dienstleistungsmarken, Handelsnamen, Produktnamen und Logos sind Eigentum ihrer jeweiligen Inhaber.