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 es KI-Assistenten ermöglicht, mit Anki, der Karteikarten-App für räumliche Wiederholung, zu interagieren.

Verwandeln Sie Ihr Anki-Erlebnis mit natürlicher Sprachinteraktion – wie ein privater 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 spontan Notizen erstellen und bearbeiten und Ihre Lernsitzungen in dynamische Gespräche verwandeln. Weitere Funktionen folgen in Kürze!

Beispiele und Tutorials

Umfassende Anleitungen, praxisnahe Beispiele und Schritt-für-Schritt-Tutorials zur Verwendung dieses MCP-Servers mit Claude Desktop finden Sie unter:

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

Siehe docs/ für ergänzende Dokumentation, einschließlich der Einrichtungsanleitung für den Reviewer und des Beispiel-Anki-Decks.

Beispiel-Anwendungsfälle

Drei repräsentative Prompts, die die von diesem Server ermöglichten Werkzeugabläufe 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 zeichnet Ihre Bewertung auf (rate_card). Natürliches Lerngespräch mit auf Sie zugeschnittenen Erklärungen.

2. "Erstelle 10 arabische Vokabelkarten mit RTL-Stil." – 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 im Stapel (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 Vorderseitenfeld mit einem <img>-Tag (updateNoteFields).

Verfügbare Werkzeuge

Der Server stellt 42 MCP-Werkzeuge bereit – 31 grundlegende Werkzeuge für alltägliche Anki-Operationen und 11 GUI-Werkzeuge, die die Anki-Desktop-Oberfläche für Notizbearbeitungs-/-erstellungsworkflows steuern.

Grundlegende Werkzeuge

Wiederholung & Lernen

• sync – Mit AnkiWeb synchronisieren, um neueste Daten abzurufen und Änderungen zu übertragen
• get_due_cards – Karten abrufen, die zur Wiederholung anstehen, optional nach Deck gefiltert
• get_cards – Karten mit flexibler Filterung nach Status (fällig, neu, lernend, ausgesetzt, vergraben) und Deck abrufen
• present_card – Eine Karte zur Wiederholung mit ihrer Frage-/Vorderseite anzeigen
• rate_card – Kartenleistung bewerten (Wieder falsch, Schwer, Gut, Einfach) und die nächste Wiederholung planen

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

Deck-Verwaltung

• listDecks – Alle Decks auflisten, optional mit kartenanzahlstatistiken pro Deck
• deckStats – Umfassende Statistiken für ein einzelnes Deck abrufen (Anzahlen, 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 nicht vorhanden)

Notizverwaltung

• addNote – Eine einzelne Notiz mit angegebenen Feldern und Tags erstellen
• addNotes – Bis zu 100 Notizen mit gemeinsamem Deck und Modell stapelweise erstellen (teilweiser Erfolg unterstützt)
• findNotes – Mit Anki-Abfragesyntax nach Notizen suchen (deck:, tag:, is:due, etc.)
• notesInfo – Detaillierte Informationen zu Notizen abrufen (Felder, Tags, CSS-Stil)
• updateNoteFields – Vorhandene Notizfelder aktualisieren (CSS-bewusst, unterstützt HTML-Inhalt)
• 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 in allen angegebenen Notizen umbenennen
• clearUnusedTags – Verwaiste Tags entfernen, die von keiner Notiz verwendet werden (destruktiv)

Medienverwaltung

• 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)

💡 Bewährte Methode 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 sich das Bild befindet, und es wird den Upload automatisch mit der effizientesten Methode durchführen.

Modell-/Vorlagenverwaltung

• modelNames – Alle verfügbaren Notiztypen/-modelle auflisten
• modelFieldNames – Feldnamen für einen bestimmten Notiztyp abrufen
• modelStyling – CSS-Stilinformationen für einen Notiztyp abrufen
• modelTemplates – Die Kartenvorlagen (Vorderseiten- 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 – Das CSS-Styling für einen vorhandenen Notiztyp aktualisieren (gilt für alle seine Karten)
• updateModelTemplates – Die Kartenvorlagen (Vorderseiten- 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 explizite Bestätigung)
• renameModelField – Ein Feld in einem vorhandenen Notiztyp umbenennen (Kartenvorlagen, die auf den alten Namen verweisen, 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
• review_stats – Analyse des Wiederholungsverlaufs (zeitliche Muster, Behaltensmetriken, Lernserien)

GUI-Werkzeuge

Werkzeuge, die die Anki-Desktop-Oberfläche steuern. Vorgesehen für Notizbearbeitungs-/-erstellungs- und Deckverwaltungs-Workflows, nicht für Wiederholungssitzungen.

• guiBrowse – Den Kartenbrowser öffnen und nach Karten suchen
• guiSelectCard – Eine bestimmte Karte im Kartenbrowser auswählen
• guiSelectedNotes – IDs der aktuell im Kartenbrowser ausgewählten Notizen abrufen
• guiAddCards – Den Dialog „Karten hinzufügen“ mit voreingestellten Notizdetails öffnen
• guiEditNote – Den Notizeditor für eine bestimmte Notiz öffnen
• guiDeckOverview – Den Deck-Übersichtsdialog für ein bestimmtes Deck öffnen
• guiDeckBrowser – Den Deck-Browser-Dialog öffnen
• guiCurrentCard – Informationen zur aktuellen Karte im Wiederholungsmodus abrufen
• guiShowQuestion – Die Frageseite 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 bekommen. Sobald er installiert ist, gehen Sie zu KI-Client verbinden, um ihn mit Ihrem KI-Assistenten zu verbinden – lokal oder remote.

npm (global oder npx)

Der universelle Weg, den Server zu installieren, geeignet für jeden MCP-Client, der ihn direkt startet.

Installieren Sie ihn global für Clients, die den Befehl ankimcp 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
   • Methode 2: Gehen Sie zu Einstellungen → Entwickler → Erweiterungen → Erweiterung installieren und wählen Sie 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 Directory: Eine Komplettanleitung mit einem vorbefüllten Beispiel-Deck finden Sie in docs/reviewer-setup.md.

Aus dem Quellcode installieren (für Entwicklung)

Für Entwicklung oder fortgeschrittene Nutzung:

npm install
npm run build

KI-Client verbinden

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 Werkzeuge.
• Remote – Ein gehosteter/entfernter KI-Assistent (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 leichtgewichtigere, 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 und andere. Der Client startet den Server als Unterprozess und kommuniziert über Standardeingabe/-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 Flag --stdio.

Konfiguration – Wählen Sie eine Methode:

Methode 1: Verwendung von 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: Verwendung der globalen Installation

Zuerst global installieren:

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

Dann konfigurieren:

{
  "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: Zugänglich über die Einstellungs-UI in VS Code
• Zed Editor: Installation als MCP-Erweiterung über den Erweiterungsmarktplatz

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 (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-Werkzeug kommuniziert, wenn es auf Ihren Rechner gerichtet ist, und es ist auch das, was die Remote-Optionen nach außen hin bereitstellen. Für sich allein bindet der HTTP-Modus nur an localhost.

Bindung über localhost hinaus? 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 DNS-Rebinding-Schutz – setzen Sie ALLOWED_HOSTS auf den/die von Clients verwendeten Hostnamen. Siehe HTTP-Modus-Konfiguration.

Einrichtung – Wählen Sie eine Methode:

Methode 1: Verwendung von 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: Globale Installation verwenden

# 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 eine in der Cloud gehostete KI erreichbar zu machen, verwenden Sie eine der folgenden Remote-Optionen.

Remote

Eine gehostete/entfernte KI (wie ChatGPT oder Claude.ai, die in der Cloud ausgeführt werden) kann localhost nicht direkt erreichen. Diese Optionen machen Ihr lokales Anki für das Internet zugänglich, sodass ein Remote-Assistent damit kommunizieren kann.

Tunnel (✅ Empfohlen)

Empfohlener Remote-Pfad — authentifiziert & sicher. Im Gegensatz zu einem ungeschützten öffentlichen Port erfordert der Tunnel-Modus eine Anmeldung (OAuth 2.0 Device Flow), sodass der Endpunkt nicht für jeden zugänglich ist, der die URL errät.

Der Tunnel-Modus ermöglicht es webbasierten KI-Assistenten, Ihr lokales Anki zu erreichen, ohne einen eigenen Tunnel betreiben zu müssen. Der Server stellt über ein WebSocket eine Verbindung zum verwalteten AnkiMCP-Tunnel-Dienst (wss://tunnel.ankimcp.ai) her und erhält eine öffentliche URL. Die Authentifizierung ist integriert – kein ngrok-Konto oder separater Tunnelprozess erforderlich, und Sie melden sich nur einmal an.

Anmelden (OAuth Device Flow):

Der Tunnel-Modus verwendet den OAuth 2.0 Device Authorization Grant. Die Anmeldung öffnet automatisch Ihren Browser mit einer Genehmigungsseite, wobei der Code bereits in die URL eingebettet ist – nichts einzutippen, nur genehmigen. (Falls 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 Ihrem KI-Assistenten mit.

Umgebungsvariablen für den Tunnel-Modus:

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

Die Device-Flow-Auth-Endpunkte (/auth/device, /auth/token) werden von TUNNEL_SERVER_URL abgeleitet, sodass ein Verweis von --tunnel (oder TUNNEL_SERVER_URL) auf einen anderen Host auch die Authentifizierung zu diesem Host verschiebt.

So funktioniert es: Der Tunnel-Modus führt den MCP-Server im Prozess hinter einem In-Memory-Transport aus (McpModule wird ohne integrierten Transport gestartet). TunnelMcpService verbindet diesen In-Memory-Transport mit dem MCP-Server, und TunnelClient überbrückt ihn über ein WebSocket mit dem Remote-Tunnel-Dienst – und leitet MCP-Anfragen hinein und Antworten hinaus. AnkiConnect wird weiterhin nur auf Ihrem lokalen Rechner erreicht.

ngrok (Unauthentifizierte Alternative)

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

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

Dieser Weg ist unauthentifiziert – jeder mit der URL kann auf Ihr Anki zugreifen, daher ist er 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 Flag --ngrok startet ngrok mit --host-header=rewrite, sodass ngrok den Upstream Host vor der Weiterleitung in localhost umschreibt. Dadurch bleiben die Anfragen innerhalb der Loopback-Host-Zulassungsliste (siehe DNS-Rebinding-Schutz), ohne dass Sie die öffentliche *.ngrok-Domäne 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 <port>              Port to listen on (HTTP mode, default: 3000)
  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
  --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

Nur-Lese-Modus (alle Modi)

Das Flag --read-only verhindert jegliche Ä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 werden blockiert (addNote, deleteNotes, createDeck, updateNoteFields usw.)
• Nützlich zum sicheren Erkunden von Anki-Daten ohne das 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 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"
      }
    }
  }
}

Mit Claude Desktop verbinden (Lokaler Modus)

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

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

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 Konfigurationsdatei

• 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	Nur-Lese-Modus aktivieren (true oder 1)	false
ALLOWED_HOSTS	HTTP-Modus: Zusätzliche Host-Header-Werte, die über Loopback hinaus akzeptiert werden (durch Kommas getrennte Hostnamen). Erforderlich bei Bindung an eine LAN-/öffentliche Adresse oder bei Ausführung hinter einem Reverse-Proxy. Siehe HTTP-Modus-Konfiguration.	nur Loopback
ALLOWED_ORIGINS	HTTP-Modus: Durch Kommas getrennte Zulassungsliste von Browser-Origin/Referer-Mustern (Wildcards werden unterstützt, z. B. https://*.ngrok.io).	http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URL	WebSocket-URL des Tunnelservers (nur Tunnel-Modus)	wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPES	Zusätzliche MIME-Typen, die für Dateipfad-Importe erlaubt sind (durch Kommas getrennt, z. B. application/pdf)	-
MEDIA_IMPORT_DIR	Dateipfad-Importe auf dieses Verzeichnis beschränken	-
MEDIA_ALLOWED_HOSTS	Bestimmte private Netzwerk-Hosts für URL-Importe erlauben (durch Kommas getrennt, z. B. 192.168.1.50,my-nas)	-

Anwendungsbeispiele

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 Tool findNotes 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 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 "hello" im Vorderseitenfeld
• "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 einem der beiden Decks

Wichtige Hinweise

CSS- und HTML-Behandlung

• Das Tool notesInfo gibt CSS-Styling-Informationen für eine korrekte Darstellungswahrnehmung zurück
• Das Tool updateNoteFields unterstützt HTML-Inhalte in Feldern und bewahrt das CSS-Styling
• Jedes Notizmodell hat sein eigenes CSS-Styling – verwenden Sie modelStyling, um modellspezifisches CSS zu erhalten

Aktualisierungswarnung

⚠️ WICHTIG: Wenn Sie updateNoteFields verwenden, zeigen Sie die Notiz NICHT im Anki-Browser an, während Sie sie aktualisieren, da die Felder sonst nicht ordnungsgemäß aktualisiert werden. Schließen Sie den Browser oder wechseln Sie zu einer anderen Notiz, bevor Sie die Aktualisierung durchführen. Weitere Details finden Sie unter Bekannte Probleme.

Löschsicherheit

Das Tool deleteNotes 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 Medientools (storeMediaFile, retrieveMediaFile, deleteMediaFile) und updateNoteFields Audio-/Bildfelder enthalten eine Sicherheitsvalidierung, um Missbrauch durch Prompt-Injection zu verhindern:

• Dateipfad-Importe sind auf Mediendateitypen beschränkt (Bilder, Audio, Video). Nicht-Mediendateien (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 auf SSRF-Angriffe überprüft. Anfragen an private Netzwerke (10.x, 172.16.x, 192.168.x), Loopback (127.x), Link-Local (169.254.x) und Nicht-HTTP(S)-Schemas 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.

Path-Traversal-Schwachstelle gemeldet von Hideaki Takahashi.

DNS-Rebinding-Schutz (HTTP-Transport)

Im HTTP-Modus validiert der Server bei jeder Anfrage den Host-Header. 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 zugelassener Host wird mit 403 abgelehnt.

Wenn Sie an 0.0.0.0 binden, hinter einem Reverse-Proxy ausführen oder eine öffentliche Tunnel-Domäne verfügbar machen, setzen Sie ALLOWED_HOSTS (durch Kommas getrennte Hostnamen), um diese Hosts zuzulassen. Beim Tunneln 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.

Datenschutzrichtlinie

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 Lernkartendaten 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 die integrierte AnkiWeb-Synchronisierung von Anki aktivieren, geschieht dies direkt zwischen Ihrer Anki-Installation und AnkiWeb – außerhalb des Geltungsbereichs dieses Servers.
• Aufbewahrung: Nicht zutreffend – es werden keine Daten serverseitig gespeichert.
• 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 stillschweigend fehl, wenn die Notiz gerade im Anki-Browserfenster angezeigt wird. Dies ist eine vorgelagerte Einschränkung von AnkiConnect.

Problemumgehung: Schließen Sie immer den Browser oder navigieren Sie zu einer anderen Notiz, bevor Sie die Aktualisierung durchführen.

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

Dies bedeutet, dass Ihre Node.js-Version nicht unterstützt wird. Der Server benötigt Node.js 22.12.0+.

Hinweis: Die mindestens unterstützte Laufzeitumgebung 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 oder höher. 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 Standardeingabe/-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; TunnelMcpService verbindet ihn mit dem MCP-Server und TunnelClient überbrückt ihn über ein WebSocket mit dem Tunneldienst
• Einstiegspunkt: dist/main-tunnel.js
• Ausführen: node dist/main-tunnel.js --tunnel (oder ankimcp --tunnel)
• Authentifizierung: ankimcp --login / ankimcp --logout; Anmeldeinformationen werden unter ~/.ankimcp/credentials.json (0600) gespeichert
• 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 erstellt. Wählen Sie basierend auf Ihren Anforderungen aus, welches Sie ausführen möchten.

HTTP-Modus-Konfiguration

Umgebungsvariablen:

• PORT - HTTP-Server-Port (Standard: 3000)
• HOST - Bindungsadresse (Standard: 127.0.0.1 nur für localhost)
• ALLOWED_HOSTS - Durch Kommas getrennte zusätzliche Host-Header-Werte, die über den integrierten Loopback-Satz hinaus akzeptiert werden sollen (localhost, 127.0.0.1, ::1). Nur Hostname und portunabhängig. Standard: nur Loopback.
• ALLOWED_ORIGINS - Durch Kommas getrennte Zulassungsliste von Browser-Origin/Referer-Mustern; 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 enthalten, der mit der Zulassungsliste übereinstimmt. Standardmäßig werden nur Loopback-Hosts (localhost, 127.0.0.1, ::1) akzeptiert, unabhängig vom Port. Host ist ein browserverbotener 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 zugelassener Host wird mit 403 abgelehnt.
• Origin-Header-Validierung – Browseranfragen mit einem vorhandenen, aber nicht zugelassenen Origin/Referer werden abgelehnt. Anfragen ohne Origin (curl, Postman, MCP-over-HTTP-Clients) sind zulässig; die Host-Validierung dient als Schutz gegen Rebinding.
• Bindet standardmäßig an localhost (127.0.0.1).
• Keine Authentifizierung in der aktuellen Version (OAuth-Unterstützung ist geplant).

HTTP-Modus über localhost hinaus verfügbar machen – 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 ohne ALLOWED_HOSTS an 0.0.0.0/:: binden, protokolliert der Server eine Startwarnung, dass nur Loopback-Host-Header akzeptiert werden.

Docker / Reverse-Proxy / öffentliche Domain: Es gilt dieselbe Regel. In Docker treffen Anfragen normalerweise mit dem veröffentlichten Hostnamen des Containers oder dem Host des Proxys ein, setzen Sie ALLOWED_HOSTS also 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 in localhost umschreiben. Die integrierte --ngrok-Integration übernimmt dies automatisch (siehe unten).

Beispiel: Ausführen von 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

So erstellen Sie ein verteilbares MCPB-Bundle:

npm run mcpb:bundle

Dieser Befehl führt Folgendes aus:

1. Synchronisiert die Version von package.json mit manifest.json
2. Entfernt alte .mcpb-Dateien
3. Erstellt das TypeScript-Projekt
4. Packt dist/ und node_modules/ in eine .mcpb-Datei
5. Führt mcpb clean aus, um devDependencies zu entfernen (optimiert das Bundle von ~47 MB auf ~10 MB)

Die Ausgabedatei erhält den Namen anki-mcp-server-X.X.X.mcpb und kann für die Ein-Klick-Installation verteilt werden.

Was gebündelt wird

Das MCPB-Bundle enthält:

• Kompiliertes JavaScript (Verzeichnis dist/ – enthält alle drei Einstiegspunkte)
• Nur Produktionsabhängigkeiten (node_modules/ – devDependencies werden durch mcpb clean entfernt)
• Paketmetadaten (package.json)
• Manifestkonfiguration (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

Bei der Ausführung als MCPB-Erweiterung in Claude Desktop werden Protokolle hier geschrieben:

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 vom Servercode) geht an stderr und erscheint in den MCP-spezifischen Protokolldateien. Claude Desktop bestimmt, welche Protokolldatei welche Nachrichten empfängt, aber im Allgemeinen gilt:

• Anwendungsstart und MCP-Protokollkommunikation → MCP-spezifisches Protokoll
• Serverinterne Protokollierung (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 von Ihrer IDE (WebStorm, VS Code usw.) anhängen.

Hinweis für den HTTP-Modus: Verwenden Sie beim Testen des HTTP-Modus (Streamable HTTP) mit dem MCP Inspector den "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

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 von Ihrer IDE anhängen

WebStorm

1. Gehen Sie zu Ausführen → Konfigurationen bearbeiten
2. Fügen Sie eine neue Konfiguration An Node.js/Chrome anhängen 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 MCP-Server debuggen (Anhängen) aus
3. Drücken Sie F5, um anzuhängen

Schritt 4: Haltepunkte setzen und debuggen

Sobald die Verbindung hergestellt ist, können Sie:

• Haltepunkte in Ihren TypeScript-Quelldateien setzen
• Die Codeausführung schrittweise durchlaufen
• Variablen und die Aufrufliste überprüfen
• Die Debug-Konsole zum Auswerten von Ausdrücken verwenden

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

Debuggen mit Claude Desktop

Sie können den MCP-Server auch debuggen, während er in Claude Desktop ausgeführt wird, 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"
      }
    }
  }
}

Wichtige Ä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 anhängt (zum Debuggen von Startproblemen)

Schritt 2: Claude Desktop neu starten

Starten Sie Claude Desktop neu, nachdem Sie die Konfiguration gespeichert haben. Der MCP-Server wird nun mit aktiviertem Debugging auf Port 9229 ausgeführt.

Schritt 3: Debugger von 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 (abhängig von der 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 An Anki MCP anhängen (Claude Desktop)
4. Drücken Sie F5, um anzuhängen

Schritt 4: Debuggen in Echtzeit

Sobald die Verbindung hergestellt 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 erreicht, wenn Werkzeuge aufgerufen werden
• Die Codeausführung schrittweise durchlaufen
• Variablen und die Aufrufliste überprüfen
• Die Debug-Konsole verwenden

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

Hinweis: Der Debugger bleibt so lange verbunden, wie Claude Desktop ausgeführt wird. Sie können die Verbindung jederzeit trennen und wiederherstellen, ohne Claude Desktop neu starten zu müssen.

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

Lokales Testen des NPM-Pakets

Testen Sie das npm-Paket lokal vor der Veröffentlichung:

# 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 mit der identisch ist, die 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 eine Mindestabdeckung von 70 % für Folgendes ein:

• 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 dann Hauptversionserhöhungen (2.0.0 usw.)

Aktueller Status: 0.22.0 – Aktive Beta-Entwicklung. Zu den neuesten Funktionen gehören die sammlungsweite Wiederholungsanalyse (review_stats aggregiert jetzt über alle Decks, wenn deck weggelassen wird), Modellfeldverwaltung (addModelField, removeModelField, renameModelField, repositionModelField), Stapelerstellung von Notizen (addNotes), integriertes ngrok-Tunneling (Flag --ngrok), Mediendateiverwaltung, Modell-/Vorlagenverwaltung und umfassende Deckstatistiken. APIs können sich basierend auf Feedback und Tests ändern.

MCPB-Spezifikationsentwicklung

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 Rahmen des 0.x.x-Versionierungsschemas zulässig.

Ähnliche Projekte

Wenn Sie Anki MCP-Integrationen erkunden, 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 Werkzeugen in einer Datei
• Geeignet für: Einfache Anwendungsfälle, minimale Abhängigkeiten

Warum sich dieses Projekt unterscheidet:

• Architektur auf Unternehmensniveau: Aufgebaut auf NestJS mit Dependency Injection
• Modularer Aufbau: Jedes Werkzeug ist eine eigene Klasse mit klarer Trennung der Verantwortlichkeiten
• Wartbarkeit: Einfach um neue Funktionen erweiterbar, ohne bestehenden Code zu verändern
• Testen: Umfassende Testsuite mit einer Anforderung von 70 % Abdeckung
• Typsicherheit: Striktes TypeScript mit Zod-Validierung
• Fehlerbehandlung: Robuste Fehlerbehandlung mit hilfreichem Benutzer-Feedback
• Produktionsreif: Ordnungsgemäße Protokollierung, Fortschrittsberichte und MCPB-Bundle-Unterstützung
• Skalierbarkeit: Kann problemlos von grundlegenden Werkzeugen 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
• Erstellen von Desktop-Erweiterungen (Anthropic Blog)
• MCP Servers Repository
• NestJS Dokumentation
• Anki Offizielle 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 nicht von diesem 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-Dokumentations-Repository und wird unter der MIT-Lizenz verwendet. Für weitere Informationen über MCP besuchen Sie 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.