Anki MCP

Anki MCP Server

[!IMPORTANT] Bevorzugen Sie das AnkiMCP-Addon für die meisten Einrichtungen.

Das Addon (GitHub) führt den MCP-Server direkt in Anki aus. Es muss kein Node.js installiert, kein AnkiConnect konfiguriert und kein separater Prozess am Laufen gehalten werden: Installieren Sie es mit dem Code 124672614, starten Sie Anki neu, und der Server läuft jedes Mal, wenn Anki geöffnet wird. Es deckt lokalen HTTP-Zugriff und Fernzugriff über einen integrierten Tunnel ab.

Dieses Repository ist die richtige Wahl, wenn Sie speziell Folgendes benötigen:

• STDIO-Transport — Claude Desktop, Claude Code, Cursor oder jeder Client, der den Server als Unterprozess startet
• MCPB-Bundle — die Ein-Klick-.mcpb-Installation für Claude Desktop

Für HTTP-, Tunnel- oder webbasierte Clients (claude.ai, ChatGPT) ist das Addon der einfachere und besser unterstützte Weg.

Dieses Repository wird nicht eingestellt. Es bleibt gepflegt und wird zusammen mit dem Addon als Teil desselben ankimcp.ai-Projekts veröffentlicht.

Ein Model Context Protocol (MCP)-Server, der es KI-Assistenten ermöglicht, mit Anki, der Karteikarten-Anwendung für verteiltes Wiederholen, zu interagieren.

Verwandeln Sie Ihr Anki-Erlebnis mit 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 Ihre Lernsitzungen in dynamische Gespräche verwandeln. Weitere Funktionen folgen in Kürze!

Beispiele und Tutorials

Für umfassende Anleitungen, Praxisbeispiele 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 des Reviewer-Einrichtungsleitfadens und des Beispiel-Anki-Decks.

Beispiel-Anwendungsfälle

Drei repräsentative Eingabeaufforderungen, die die Tool-Abläufe zeigen, die dieser Server ermöglicht:

1. „Hilf mir, mein Spanisch-Deck zu wiederholen." — Der Assistent bietet an, mit AnkiWeb zu synchronisieren (sync), ruft fällige Karten ab (get_due_cards mit Deck-Filter), präsentiert jede Karte (present_card) und zeichnet Ihre Bewertung auf (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 ausgewählte Notiz aus dem Browser (guiSelectedNotes + notesInfo) und aktualisiert das Vorderseiten-Feld mit einem <img>-Tag (updateNoteFields).

Verfügbare Tools

Der Server stellt 53 MCP-Tools bereit – 42 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

Wiederholung & Lernen

• sync – Mit AnkiWeb synchronisieren, um neueste Daten zu ziehen und Änderungen zu pushen
• get_due_cards – Fällige Karten abrufen, optional nach Deck gefiltert (Antworten weggelassen, 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 weggelassen, 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 aufzuzeichnen
• setDueDate – Karten neu planen, sodass sie in N Tagen fällig werden ("0", "3-7", "1!"), ohne eine Wiederholung aufzuzeichnen
• areSuspended – Aussetzungsstatus für eine oder mehrere Karten prüfen, ohne etwas zu ändern
• suspend – Karten aussetzen, damit sie bei der Wiederholung übersprungen werden, bis sie wieder aktiviert werden
• unsuspend – Karten reaktivieren, damit sie zur normalen Wiederholung zurückkehren

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, zeichnet einen echten Fehler auf 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 den Verlauf 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 wird, 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 – daher ist review nicht „reife Karten" und der other-Eimer ist nur der arithmetische Rest (hauptsächlich 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, wobei Fälligkeitsdaten und Tageslimits ignoriert werden.

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 – Nach Notizen mit Anki-Abfragesyntax suchen (deck:, tag:, is:due usw.)
• notesInfo – Detaillierte Informationen über Notizen abrufen (Felder, Tags, Notiztyp, Karten-IDs; CSS kommt von modelStyling)
• updateNoteFields – Vorhandene Notizfelder aktualisieren (CSS-bewusst, unterstützt HTML-Inhalt)
• deleteNotes – Notizen und alle zugehörigen Karten löschen (zerstörerisch, erfordert Bestätigung)

Tag-Verwaltung

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

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 (zerstörerisch)

💡 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 durchführen.

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 (Anki schreibt Verweise auf den alten Namen in den Kartenvorlagen um)
• 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. Gedacht für Notizbearbeitungs-/Erstellungsworkflows und Deck-Verwaltung, nicht für Wiederholungssitzungen.

• guiBrowse – Den Karten-Browser öffnen und nach Karten suchen
• guiSelectCard – Eine bestimmte Karte im Karten-Browser auswählen
• guiSelectedNotes – IDs von Notizen abrufen, die aktuell im Karten-Browser ausgewählt sind
• 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 über die aktuelle Karte im Wiederholungsmodus abrufen (enthält die Antwort; Fehler außerhalb des Wiederholungsmodus)
• 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 Ihren Rechner zu bringen. Sobald er installiert ist, gehen Sie zu Verbinden eines KI-Clients, um ihn mit Ihrem KI-Assistenten zu verbinden – lokal oder remote.

npm (global oder npx)

Die allgemeine Methode 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 Komplettanleitung 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 (das Ausführen 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 Browsersitzung). 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 Standardtransport für lokale Desktop-MCP-Clients — Claude Desktop, Cursor IDE, Cline, Zed Editor, opencode 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
• opencode - Terminal-KI-Coding-Agent
• 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"
      }
    }
  }
}

opencode verwendet ein eigenes Format — Server werden unter mcp eingetragen, der Befehl ist ein einzelnes Array, und Umgebungsvariablen kommen unter environment:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "anki-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "enabled": true,
      "environment": {
        "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 Einstellungs-UI in VS Code erreichbar
• Zed Editor: Als MCP-Erweiterung über den Erweiterungs-Marketplace installieren
• opencode: opencode.json im Projektstamm oder ~/.config/opencode/opencode.json global

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

HTTP (lokale webbasierte 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 bindet der HTTP-Modus nur an localhost.

Über localhost hinaus binden? Wenn Sie --host 0.0.0.0 übergeben (oder hinter einem Reverse-Proxy/öffentlicher Domain laufen), akzeptiert der Server standardmäßig nur Loopback-Host-Header zum Schutz vor DNS-Rebinding — setzen Sie ALLOWED_HOSTS auf 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 Entwicklung)

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

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

Remote

Eine gehostete/Remote-KI (wie ChatGPT oder Claude.ai in der Cloud) kann localhost nicht direkt erreichen. Diese Optionen machen Ihr lokales Anki im Internet erreichbar, sodass ein Remote-Assistent damit sprechen kann.

Tunnel (✅ Empfohlen)

Empfohlener Remote-Pfad — authentifiziert & sicher. Anders als ein roher öffentlicher Port erfordert der Tunnelmodus eine Anmeldung (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 zu betreiben. Der Server verbindet sich ausgehend mit dem verwalteten AnkiMCP-Tunneldienst (wss://tunnel.ankimcp.ai) über einen WebSocket 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 die OAuth-2.0-Geräteautorisierung. Beim Anmelden öffnet sich Ihr Browser automatisch mit einer Genehmigungsseite, wobei der Code bereits in der URL eingebettet ist — nichts zum Eintippen, einfach genehmigen. (Wenn der Browser nicht geöffnet werden kann, gibt das Terminal eine Verifizierungs-URL und einen Code aus, die manuell als Fallback eingegeben werden können.) Bei Erfolg werden die Anmeldedaten 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 Anmeldedaten vorhanden sind, startet --tunnel automatisch zuerst den Anmeldefluss 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 zum Trennen. Teilen Sie diese URL mit Ihrem KI-Assistenten.

Umgebungsvariablen im 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. Fortgeschritten — nur erforderlich, wenn auf einen selbst gehosteten Tunnel-/Auth-Dienst gezeigt wird.	(integriert)

Die Gerätefluss-Auth-Endpunkte (/auth/device, /auth/token) werden von TUNNEL_SERVER_URL abgeleitet, sodass das Zeigen von --tunnel (oder TUNNEL_SERVER_URL) auf einen anderen Host 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 verwandelt jeden weitergeleiteten Anfragetext in eine Antwort, und TunnelClient verbindet ihn über einen WebSocket mit dem entfernten Tunneldienst — MCP-Anfragen werden hinein- und Antworten hinausgeleitet. 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 Revision 2026-07-28 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 (nicht authentifizierte Alternative)

Wenn Sie den lokalen HTTP-Modus lieber öffentlich verfügbar 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 nicht authentifiziert — jeder mit der URL kann Ihr Anki erreichen, daher ist sie weniger sicher als Tunnel. Bevorzugen Sie den Tunnel, es sei denn, Sie haben einen spezifischen 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 Upstream-Host in localhost umschreibt, bevor es weiterleitet. Das hält Anfragen 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 content changes and rescheduling; rating, suspend and sync still work)
  --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

Nur-Lese-Modus (alle Modi)

Das --read-only-Flag (oder READ_ONLY=true) blockiert Änderungen an Notizinhalten, Decks, Tags, Medien und Notiztypen sowie das manuelle Neuplanen von Karten. Wenn aktiviert:

• Alle Leseoperationen funktionieren normal (Decks durchsuchen, Karten anzeigen, Notizen suchen)
• Diese Änderungen sind weiterhin erlaubt: Bewerten einer Karte während der Wiederholung (rate_card), Suspendieren/Reaktivieren von Karten (suspend, unsuspend), Synchronisieren mit AnkiWeb (sync) und die GUI-Tools, die durch Ankis Fenster navigieren (guiBrowse, guiDeckOverview, …)
• Inhaltsänderungen sind blockiert (addNote, deleteNotes, createDeck, updateNoteFields usw.); createDeck für ein bereits vorhandenes Deck ist weiterhin erfolgreich, da nichts geschrieben wird
• Manuelles Neuplanen ist blockiert: forgetCards (auf „Neu“ zurücksetzen) und setDueDate
• guiUndo ist blockiert, da ein Rückgängigmachen eine Änderung an der Sammlung rückgängig machen kann
• guiAddCards und guiEditNote sind blockiert, da eine im geöffneten Dialog hinzugefügte oder gespeicherte Notiz in die Sammlung geschrieben wird
• Nützlich zum Erkunden von Anki-Daten ohne versehentliche Änderungen an deren Inhalt

# 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 Nur-Lese-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"
      }
    }
  }
}

Verbinden mit Claude Desktop (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	Anfragetimeout in ms	5000
READ_ONLY	Nur-Lese-Modus aktivieren (true oder 1)	false
PORT	HTTP-Modus: Port zum Zuhö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 (Wildcards 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 Netzwerkhosts für URL-Importe zulassen (kommagetrennt, z. B. 192.168.1.50,my-nas)	-

Verwendungsbeispiele

Suchen und Aktualisieren von Notizen

# 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 Ankis leistungsstarke Abfragesyntax:

• "deck:DeckName" - Alle Notizen in einem bestimmten Deck
• "tag:important" - Notizen mit dem Tag „wichtig“
• "is:due" - Karten, die zur Wiederholung anstehen
• "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 „Hallo“ im Vorderfeld
• "flag:1" - Notizen mit roter Markierung
• "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 den Notiztypnamen jeder Notiz zurück; das CSS selbst stammt von modelStyling
• 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 korrekt aktualisiert werden. Schließen Sie den Browser oder wechseln Sie zu einer anderen Notiz, bevor Sie aktualisieren. Weitere Details finden Sie unter Bekannte Probleme.

Löschsicherheit

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

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:

• Dateipfad-Importe sind auf Mediendateitypen beschränkt (Bilder, Audio, Video). Nicht-Medien-Dateien (z. B. SSH-Schlüssel, Anmeldedaten, 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. Anfragen an private Netzwerke (10.x, 172.16.x, 192.168.x), Loopback (127.x), Link-Local (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.

Schwachstelle bei Pfad-Traversal gemeldet von Hideaki Takahashi.

DNS-Rebinding-Schutz (HTTP-Transport)

Im HTTP-Modus validiert der Server 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 vom Browser verbotener Header, sodass eine bösartige Webseite ihn nicht fälschen kann – dies schließt den DNS-Rebinding-Pfad, bei dem eine zurückgebundene 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 sammelt keine Telemetrie-, Analyse- oder Nutzungsdaten.

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

• Datenerfassung: Der Server sammelt nichts. Er leitet Anfragen zwischen Ihrem KI-Assistenten und Ihrem lokalen AnkiConnect-Plugin weiter.
• Nutzung / Speicherung: Keine serverseitige Speicherung. Alle Karteikartendaten bleiben 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 Geltungsbereichs 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 fehl, wenn sie im Browser angezeigt werden

⚠️ WICHTIG: Wenn Sie Notizen mit updateNoteFields aktualisieren, schlägt die Aktualisierung still fehl, wenn die Notiz gerade im Anki-Browserfenster angezeigt wird. Dies ist eine Einschränkung von AnkiConnect.

Problemumgehung: Schließen Sie immer den Browser 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)
• Standard-Host: 127.0.0.1 (konfigurierbar über die Umgebungsvariable HOST)
• MCP-Endpunkt: http://127.0.0.1:3000/ (Stammpfad)

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 MCP-Revision 2025 (STDIO und HTTP bedienen ebenfalls 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 möchten.

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 Zulassungsliste für Browser-Origin/Referer-Muster; Platzhalter 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 Zulassungsliste entspricht. Standardmäßig werden nur Loopback-Hosts (localhost, 127.0.0.1, ::1) akzeptiert, unabhängig vom Port. Host ist ein vom Browser verbotener Header, sodass eine bösartige Webseite ihn nicht fälschen kann – dies schließt den DNS-Rebinding-Pfad, bei dem eine zurückgebundene 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 platzieren, 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ührende Modi

# 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 ~47MB auf ~10MB)

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

Was im Bundle enthalten ist

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-Logger-Ausgabe (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

So zeigen Sie Protokolle in Echtzeit an:

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: Starten Sie den Debug-Server

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

npm run inspector:debug

Dadurch wird der Server mit aktiviertem Node.js-Debugging auf Port 9229 gestartet und die Ausführung in der ersten Zeile angehalten.

Schritt 3: Debugger aus Ihrer IDE anhängen

WebStorm

1. Gehen Sie zu Run → Edit Configurations
2. Fügen Sie eine neue Attach to Node.js/Chrome-Konfiguration hinzu
3. Setzen Sie den Port auf 9229
4. Klicken Sie auf Debug, um den Debugger 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 den Debugger anzuhängen

Schritt 4: Haltepunkte setzen und debuggen

Sobald der Debugger angehängt ist, können Sie:

• Haltepunkte in Ihren TypeScript-Quelldateien setzen
• Schrittweise durch die Codeausführung gehen
• Variablen und Aufrufliste 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 den kompilierten JavaScript-Code.

Debugging 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 anhalten, bis der Debugger angehängt ist (zum Debuggen von Startproblemen)

Schritt 2: Claude Desktop neu starten

Nach dem Speichern der Konfiguration starten Sie Claude Desktop neu. Der MCP-Server wird nun mit aktiviertem Debugging auf Port 9229 ausgeführt.

Schritt 3: Debugger aus Ihrer IDE anhängen

WebStorm

1. Gehen Sie zu Run → Edit Configurations
2. Klicken Sie auf die Schaltfläche + und wählen Sie Attach to Node.js/Chrome
3. Konfigurieren Sie:
   • Name: Attach to Anki MCP (Claude Desktop)
   • Host: localhost
   • Port: 9229
   • Attach to: Node.js < 8 oder Chrome or Node.js > 6.3 (abhängig von der WebStorm-Version)
4. Klicken Sie auf OK
5. Klicken Sie auf Debug (Umschalt+F9), um den Debugger 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 den Debugger anzuhängen

Schritt 4: In Echtzeit debuggen

Sobald der Debugger angehängt ist, können Sie:

• Haltepunkte in Ihren 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
• Schrittweise durch die Codeausführung gehen
• Variablen und Aufrufliste untersuchen
• Die Debug-Konsole verwenden

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

Hinweis: Der Debugger bleibt angehängt, solange Claude Desktop läuft. Sie können den Debugger jederzeit trennen 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)

Testen Sie das npm-Paket lokal, bevor Sie es veröffentlichen:

# 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 können Sie die vollständige Benutzererfahrung testen, bevor Sie auf npm veröffentlichen

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 für:

• Branches
• Funktionen
• Zeilen
• Anweisungen

Abdeckungsberichte werden im Verzeichnis coverage/ generiert.

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 akzeptabel

• 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.27.0 - Aktive Beta-Entwicklung. Zu den aktuellen 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 Sie Anki-MCP-Integrationen erkunden möchten, finden Sie hier 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: Auf NestJS mit Dependency Injection aufgebaut
• Modulares Design: Jedes Tool ist eine separate Klasse mit klarer Trennung der Zuständigkeiten
• Wartbarkeit: Einfach um neue Funktionen erweiterbar, ohne vorhandenen Code zu berühren
• 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 Sie eine solide Grundlage für den Aufbau fortgeschrittener Anki-Integrationen benötigen oder die Funktionalität erheblich erweitern möchten, 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
• Building Desktop Extensions (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 besuchen Sie 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 finden Sie 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.