Anki MCP

officiel

Un serveur MCP qui permet aux assistants IA d'interagir avec Anki, l'application de flashcards à répétition espacée.

GitHub

539

Que pouvez-vous faire avec Anki MCP ?

Review due cards — Demandez à votre assistant de récupérer les cartes arrivées à échéance d’un paquet spécifique et de vous les faire réviser avec get_due_cards et present_card.
Rate card performance — Faites enregistrer par l’assistant la qualité de vos réponses (Again, Hard, Good, Easy) pour reprogrammer les révisions via rate_card.
Create custom flashcards — Demandez à l’assistant de créer de nouveaux types de notes avec des champs personnalisés et un style RTL en utilisant createModel et updateModelStyling, puis d’ajouter des notes en lot avec addNotes.
Manage note content — Recherchez des notes avec la syntaxe de requête Anki (deck:, tag:, is:due) via findNotes, puis mettez à jour leurs champs avec updateNoteFields.
Import media into cards — Demandez à l’assistant de téléverser une image depuis un chemin local ou une URL avec storeMediaFile et de l’insérer dans le champ d’une note sélectionnée à l’aide de guiSelectedNotes et updateNoteFields.
Organize decks and cards — Créez des paquets imbriqués (Parent::Child) avec createDeck, déplacez des cartes entre paquets avec changeDeck, ou suspendez des cartes avec suspend pour les ignorer pendant la révision.

Documentation

Serveur Anki MCP

Intégrez de manière transparente Anki aux assistants IA via le Model Context Protocol

[!IMPORTANT] Privilégiez l'addon AnkiMCP pour la plupart des configurations.

L'addon (GitHub) exécute le serveur MCP directement dans Anki. Pas de Node.js à installer, pas d'AnkiConnect à configurer, pas de processus séparé à maintenir : installez-le avec le code 124672614, redémarrez Anki, et le serveur est opérationnel à chaque ouverture d'Anki. Il couvre l'accès HTTP local et l'accès distant via un tunnel intégré.

Ce dépôt est le bon choix lorsque vous avez spécifiquement besoin de :

Transport STDIO — Claude Desktop, Claude Code, Cursor, ou tout client qui lance le serveur comme sous-processus

Bundle MCPB — l'installation en un clic .mcpb pour Claude Desktop

Pour HTTP, tunnel, ou les clients web (claude.ai, ChatGPT), l'addon est le chemin le plus simple et le mieux pris en charge.

Ce dépôt n'est pas déprécié. Il reste maintenu et publié aux côtés de l'addon dans le cadre du même projet ankimcp.ai.

Un serveur Model Context Protocol (MCP) qui permet aux assistants IA d'interagir avec Anki, l'application de cartes mémoire à répétition espacée.

Transformez votre expérience Anki avec une interaction en langage naturel — comme si vous aviez un tuteur privé. L'assistant IA ne se contente pas de présenter des questions et réponses ; il peut expliquer des concepts, rendre le processus d'apprentissage plus engageant et plus humain, fournir du contexte, et s'adapter à votre style d'apprentissage. Il peut créer et modifier des notes à la volée, transformant vos sessions d'étude en conversations dynamiques. Plus de fonctionnalités à venir !

Exemples et tutoriels

Pour des guides complets, des exemples concrets et des tutoriels pas à pas sur l'utilisation de ce serveur MCP avec Claude Desktop, visitez :

ankimcp.ai — Documentation complète avec des exemples pratiques et des cas d'utilisation

Voir docs/ pour la documentation complémentaire, y compris le guide de configuration du reviewer et le jeu de cartes Anki d'exemple.

Exemples de cas d'utilisation

Trois invites représentatives montrant les flux d'outils activés par ce serveur :

« Aide-moi à réviser mon jeu de cartes espagnol. » — L'assistant propose de synchroniser avec AnkiWeb (sync), récupère les cartes à réviser (get_due_cards avec filtre de jeu), présente chaque carte (present_card), et enregistre votre évaluation (rate_card). Conversation d'étude naturelle avec des explications adaptées à vous.
« Crée 10 cartes de vocabulaire arabe avec un style RTL. » — L'assistant liste les types de notes (modelNames), crée un modèle RTL personnalisé si nécessaire (createModel + updateModelStyling pour le CSS droite-à-gauche), puis crée les cartes en lot (addNotes).
« Importe cette image de mon dossier Téléchargements au recto de la note sélectionnée. » — L'assistant téléverse le fichier local (storeMediaFile avec un chemin de fichier), lit la note actuellement sélectionnée dans le navigateur (guiSelectedNotes + notesInfo), et met à jour le champ recto avec une balise <img> (updateNoteFields).

Outils disponibles

Le serveur expose 53 outils MCP — 42 outils essentiels pour les opérations Anki quotidiennes et 11 outils GUI qui pilotent l'interface de bureau Anki pour les flux de création/édition de notes.

Outils essentiels

Révision et étude

sync - Synchronise avec AnkiWeb pour récupérer les dernières données et pousser les modifications
get_due_cards - Récupère les cartes à réviser, éventuellement filtrées par jeu (réponses omises sauf si include_answer: true, défaut false)
get_cards - Récupère les cartes avec un filtrage flexible par état (à réviser, nouvelles, en apprentissage, suspendues, enterrées) et par jeu (réponses omises sauf si include_answer: true, défaut false)
present_card - Affiche une carte pour révision avec son recto/question
rate_card - Évalue la performance de la carte (Encore, Difficile, Bien, Facile) et planifie la prochaine révision
forgetCards - Réinitialise les cartes à l'état nouveau, en supprimant leur planification sans enregistrer de révision
setDueDate - Replanifie les cartes pour qu'elles soient à réviser dans N jours ("0", "3-7", "1!"), sans enregistrer de révision
areSuspended - Vérifie l'état de suspension d'une ou plusieurs cartes sans rien modifier
suspend - Suspend les cartes pour qu'elles soient ignorées pendant la révision jusqu'à désuspension
unsuspend - Désuspend les cartes pour qu'elles reviennent en révision normale

Remarque : forgetCards et setDueDate modifient la planification sans enregistrer de révision, ce qui les distingue de rate_card. Utilisez-les lorsque la planification d'une carte est erronée plutôt que la réponse : évaluer une carte Again pour l'enterrer plus profondément enregistre un vrai échec et réduit son facteur de facilité, faussant définitivement à la fois la planification future et vos statistiques. forgetCards efface l'intervalle et recommence la carte ; setDueDate conserve l'historique de la carte et déplace simplement la prochaine révision.

Remarque : Le contenu des cartes front/back est rendu par carte selon son propre modèle (comme Anki l'affiche), donc les cartes inversées et à trous affichent la bonne direction. Le texte statique ajouté par vos modèles de cartes apparaît également dans la sortie.

Gestion des jeux

listDecks - Liste tous les jeux, éventuellement avec des statistiques de file d'étude par jeu
deckStats - Obtient des statistiques complètes pour un seul jeu (file d'étude, comptages réels d'états de cartes, distributions facilité/intervalle)
createDeck - Crée un nouveau jeu vide (prend en charge Parent::Child, max 2 niveaux)
changeDeck - Déplace des cartes vers un autre jeu (créé s'il n'existe pas)

Remarque : Les statistiques de jeu existent en deux variantes. Le bloc counts (et tout ce que listDecks rapporte) reflète le navigateur de jeux d'Anki : cartes à réviser aujourd'hui, plafonnées par les limites quotidiennes nouvelles/révisions de chaque jeu, avec les cartes suspendues et enterrées exclues — donc review n'est pas « cartes matures » et le compartiment other n'est que le reste arithmétique (principalement les cartes de révision non dues aujourd'hui plus les nouvelles cartes au-delà de la limite quotidienne). Pour les totaux réels par état, utilisez le bloc states sur deckStats / collection_stats, qui compte new, learning, review, suspended et buried via les recherches Anki, en ignorant les dates d'échéance et les limites quotidiennes.

Gestion des notes

addNote - Crée une seule note avec des champs et balises spécifiés
addNotes - Crée en lot jusqu'à 100 notes partageant un jeu et un modèle (succès partiel pris en charge)
findNotes - Recherche des notes avec la syntaxe de requête Anki (deck:, tag:, is:due, etc.)
notesInfo - Obtient des informations détaillées sur les notes (champs, balises, type de note, IDs de cartes ; le CSS provient de modelStyling)
updateNoteFields - Met à jour les champs de notes existantes (sensible au CSS, prend en charge le contenu HTML)
deleteNotes - Supprime des notes et toutes les cartes associées (destructif, nécessite confirmation)

Gestion des balises

getTags - Obtient toutes les balises de la collection (utilisez d'abord pour éviter la duplication)
addTags - Ajoute des balises séparées par des espaces aux notes spécifiées
removeTags - Supprime des balises séparées par des espaces des notes spécifiées
replaceTags - Renomme une balise sur les notes spécifiées
clearUnusedTags - Supprime les balises orphelines non utilisées par aucune note (destructif)

Gestion des médias

getMediaFilesNames - Liste les fichiers média dans collection.media, éventuellement filtrés par motif
retrieveMediaFile - Télécharge un fichier média en contenu base64
storeMediaFile - Téléverse un média depuis des données base64, un chemin de fichier absolu, ou une URL
deleteMediaFile - Supprime un fichier média de collection.media (destructif)

💡 Bonne pratique pour les images :

✅ Utilisez des chemins de fichiers (par ex., /Users/you/image.png) - Rapide et efficace
✅ Utilisez des URLs (par ex., https://example.com/image.jpg) - Téléchargement direct
❌ Évitez le base64 - Extrêmement lent et inefficace en tokens

Dites simplement à Claude où se trouve l'image, et il gérera le téléversement automatiquement en utilisant la méthode la plus efficace.

Gestion des modèles/modèles de cartes

modelNames - Liste tous les types de notes/modèles disponibles
modelFieldNames - Obtient les noms de champs pour un type de note spécifique
modelStyling - Obtient les informations de style CSS pour un type de note
modelTemplates - Obtient les modèles de cartes (HTML Recto et Verso) pour un type de note
createModel - Crée un nouveau type de note avec des champs personnalisés, des modèles de cartes et du CSS (par ex., modèles RTL)
updateModelStyling - Met à jour le style CSS d'un type de note existant (s'applique à toutes ses cartes)
updateModelTemplates - Met à jour les modèles de cartes (HTML Recto et Verso) d'un type de note existant (s'applique à toutes ses cartes)
addModelField - Ajoute un nouveau champ à un type de note existant (ajouté à la fin ou inséré à une position spécifique)
removeModelField - Supprime un champ d'un type de note existant (supprime son contenu de toutes les notes ; nécessite confirmation explicite)
renameModelField - Renomme un champ dans un type de note existant (Anki réécrit les références à l'ancien nom dans les modèles de cartes)
repositionModelField - Change la position d'un champ dans un type de note existant

Statistiques

collection_stats - Statistiques agrégées sur tous les jeux avec ventilation par jeu et comptages d'états de cartes à l'échelle de la collection
review_stats - Analyse de l'historique de révision (schémas temporels, métriques de rétention, séries d'étude)

Outils GUI

Outils qui pilotent l'interface de bureau Anki. Destinés aux flux de création/édition de notes et de gestion de jeux, pas aux sessions de révision.

guiBrowse - Ouvre le navigateur de cartes et recherche des cartes
guiSelectCard - Sélectionne une carte spécifique dans le navigateur de cartes
guiSelectedNotes - Obtient les IDs des notes actuellement sélectionnées dans le navigateur de cartes
guiAddCards - Ouvre la boîte de dialogue Ajouter des cartes avec des détails de note prédéfinis
guiEditNote - Ouvre l'éditeur de notes pour une note spécifique
guiDeckOverview - Ouvre la boîte de dialogue Vue d'ensemble du jeu pour un jeu spécifique
guiDeckBrowser - Ouvre la boîte de dialogue Navigateur de jeux
guiCurrentCard - Obtient des informations sur la carte actuelle en mode révision (inclut la réponse ; erreur hors mode révision)
guiShowQuestion - Affiche le recto de la carte actuelle
guiShowAnswer - Affiche le verso de la carte actuelle
guiUndo - Annule la dernière action dans Anki

Prérequis

Anki avec le plugin AnkiConnect installé
Node.js 22.12.0+

Installation

Il existe plusieurs façons d'installer le serveur sur votre machine. Une fois installé, rendez-vous sur Connexion d'un client IA pour le connecter à votre assistant IA — localement ou à distance.

npm (global ou npx)

La méthode généraliste pour installer le serveur, adaptée à tout client MCP qui le lance directement.

Installez-le globalement pour les clients qui exécutent la commande ankimcp :

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

Ou exécutez-le à la demande sans installation :

npx @ankimcp/anki-mcp-server

Bundle MCPB (recommandé pour Claude Desktop)

Le moyen le plus simple d'installer ce serveur MCP pour Claude Desktop :

Téléchargez le dernier bundle .mcpb depuis la page Releases
Dans Claude Desktop, installez l'extension :
- Méthode 1 : Allez dans Paramètres → Extensions, puis glissez-déposez le fichier .mcpb
- Méthode 2 : Allez dans Paramètres → Développeur → Extensions → Installer une extension, puis sélectionnez le fichier .mcpb
Configurez l'URL AnkiConnect si nécessaire (par défaut http://localhost:8765)
Redémarrez Claude Desktop

C'est tout ! Le bundle inclut tout le nécessaire pour exécuter le serveur localement.

Pour les relecteurs de l'annuaire MCP d'Anthropic : une procédure pas à pas de zéro à l'intégration avec un jeu d'exemple pré-rempli se trouve dans docs/reviewer-setup.md.

Installation depuis les sources (pour le développement)

Pour le développement ou une utilisation avancée (l’exécution de la suite de tests nécessite Node.js 24.9+ — les scripts de test npm chargent les paquets NestJS 12 exclusivement ESM via require(esm), que Jest ne prend en charge qu’à partir de cette version ; l’exigence d’exécution pour utiliser le serveur reste 22.12.0+) :

npm install
npm run build

Connexion d’un client IA

Il existe deux façons pour un assistant IA d’atteindre ce serveur, selon l’endroit où l’assistant s’exécute :

Local — le serveur s’exécute sur la même machine que le client IA (Claude Desktop, Cursor, Cline, Zed, ou une session de navigateur locale). Utilisez STDIO pour les clients MCP de bureau, HTTP pour les outils web locaux.
Distant — une IA hébergée/distance (par ex. ChatGPT ou Claude.ai dans le cloud) doit atteindre Anki qui s’exécute sur votre machine locale. Utilisez le Tunnel géré (✅ recommandé — authentifié) ou, comme alternative non authentifiée plus légère, ngrok.

Local

Le serveur s’exécute sur le même ordinateur que votre client IA et communique avec AnkiConnect sur localhost.

STDIO (intégration locale principale)

STDIO est le transport standard pour les clients MCP de bureau locaux — Claude Desktop, Cursor IDE, Cline, Zed Editor, opencode, et autres. Le client lance le serveur comme sous-processus et communique via l’entrée/sortie standard.

Clients pris en charge :

Claude Desktop
Cursor IDE — éditeur de code propulsé par IA
Cline — extension VS Code pour l’assistance IA
Zed Editor — éditeur de code rapide et moderne
opencode — agent de codage IA en terminal
Autres clients MCP prenant en charge le transport STDIO

Pour Claude Desktop, le bundle MCPB est le chemin le plus simple. Pour les autres clients, configurez le paquet npm avec l’indicateur --stdio.

Configuration — Choisissez une méthode :

Méthode 1 : Utilisation de npx (recommandé — aucune installation nécessaire)

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

Méthode 2 : Utilisation d’une installation globale

D’abord, installez globalement :

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

Ensuite, configurez :

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

opencode utilise son propre format — les serveurs vont sous mcp, la commande est un tableau unique, et les variables d’environnement vont sous 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"
      }
    }
  }
}

Emplacements des fichiers de configuration :

Cursor IDE : ~/.cursor/mcp.json (macOS/Linux) ou %USERPROFILE%\.cursor\mcp.json (Windows)
Cline : accessible via l’interface des paramètres dans VS Code
Zed Editor : installez comme extension MCP via la place de marché des extensions
opencode : opencode.json dans la racine de votre projet, ou ~/.config/opencode/opencode.json globalement

Pour les fonctionnalités spécifiques aux clients et le dépannage, consultez la documentation de votre client MCP. Voir aussi Connect to Claude Desktop pour une configuration qui pointe directement vers un dist/main-stdio.js construit.

HTTP (IA web locale)

Le mode HTTP exécute le serveur comme un serveur web local parlant le protocole MCP Streamable HTTP. C’est le transport qu’un outil IA basé sur le web utilise lorsqu’il est pointé vers votre machine, et c’est aussi ce que les options Distant exposent au monde extérieur. En soi, le mode HTTP se lie à localhost uniquement.

Liaison au-delà de localhost ? Si vous passez --host 0.0.0.0 (ou exécutez derrière un proxy inverse/domaine public), le serveur n’accepte que les en-têtes Host en boucle locale par défaut pour la protection contre le rebinding DNS — définissez ALLOWED_HOSTS sur le(s) nom(s) d’hôte que les clients utilisent. Voir Configuration du mode HTTP.

Configuration — Choisissez une méthode :

Méthode 1 : Utilisation de npx (recommandé — aucune installation nécessaire)

# 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

Méthode 2 : Utilisation d’une installation globale

# 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

Méthode 3 : Installation depuis la source (pour le développement)

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

Pour rendre un serveur HTTP local accessible à une IA hébergée dans le cloud, utilisez l’une des options Distant ci-dessous.

Distant

Une IA hébergée/distance (telle que ChatGPT ou Claude.ai s’exécutant dans le cloud) ne peut pas atteindre localhost directement. Ces options exposent votre Anki local sur Internet afin qu’un assistant distant puisse y parler.

Tunnel (✅ Recommandé)

Chemin distant recommandé — authentifié et sécurisé. Contrairement à un port public brut, le mode tunnel exige que vous vous connectiez (flux d’appareil OAuth 2.0), donc le point de terminaison n’est pas ouvert à quiconque devine l’URL.

Le mode tunnel permet aux assistants IA basés sur le web d’atteindre votre Anki local sans exécuter votre propre tunnel. Le serveur se connecte au service de tunnel géré AnkiMCP (wss://tunnel.ankimcp.ai) via un WebSocket et se voit attribuer une URL publique. L’authentification est intégrée — aucun compte ngrok ni processus de tunnel séparé requis, et vous vous connectez une seule fois.

Connexion (flux d’appareil OAuth) :

Le mode tunnel utilise l’octroi d’autorisation d’appareil OAuth 2.0. La connexion ouvre automatiquement votre navigateur vers une page d’approbation avec le code déjà intégré dans l’URL — rien à taper, approuvez simplement. (Si le navigateur ne peut pas s’ouvrir, le terminal affiche une URL de vérification et un code à saisir manuellement comme solution de secours.) En cas de succès, les identifiants sont enregistrés dans ~/.ankimcp/credentials.json (permissions de fichier 0600).

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

# Clear saved credentials
ankimcp --logout

Démarrez le tunnel :

# 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

Si aucun identifiant n’existe, --tunnel démarre automatiquement le flux de connexion d’abord, puis continue vers le tunnel. Cette connexion automatique nécessite un terminal interactif — lorsque la sortie standard n’est pas un TTY (systemd, Docker sans tête, CI), le serveur échoue rapidement et vous demande d’exécuter ankimcp --login d’abord. Une fois connecté, l’URL publique du tunnel est affichée ; appuyez sur Ctrl+C pour vous déconnecter. Partagez cette URL avec votre assistant IA.

Variables d’environnement du mode tunnel :

Variable	Description	Défaut
`TUNNEL_SERVER_URL`	URL WebSocket du serveur tunnel (la valeur de l’indicateur `--tunnel`/`--login` remplace ceci)	`wss://tunnel.ankimcp.ai`
`TUNNEL_AUTH_CLIENT_ID`	ID client OAuth pour le flux d’appareil. Avancé — uniquement nécessaire lors du pointage vers un service tunnel/auth auto-hébergé.	(intégré)

Les points de terminaison d’authentification du flux d’appareil (/auth/device, /auth/token) sont dérivés de TUNNEL_SERVER_URL, donc pointer --tunnel (ou TUNNEL_SERVER_URL) vers un hôte différent déplace également l’authentification vers cet hôte.

Comment cela fonctionne : Le mode tunnel exécute le serveur MCP en processus derrière un transport en mémoire (TunnelTransport). Ce transport possède le serveur MCP et transforme chaque corps de requête relayé en réponse, et TunnelClient le relie au service tunnel distant via un WebSocket — relayant les requêtes MCP entrantes et les réponses sortantes. AnkiConnect n’est toujours atteint que sur votre machine locale.

Révisions de protocole : Parce que le tunnel connecte le serveur MCP en processus, le mode tunnel ne sert que la révision 2025 du protocole MCP, tandis que les modes STDIO et HTTP servent à la fois 2025 et la révision plus récente 2026-07-28. Chaque outil se comporte de la même manière dans les deux cas — mais un client qui ne parle que 2026-07-28 est refusé via le tunnel avec une erreur de version de protocole ; exécutez le mode STDIO ou HTTP pour ce client.

ngrok (alternative non authentifiée)

Si vous préférez exposer le mode HTTP local publiquement sans compte sur le tunnel géré, l’indicateur intégré --ngrok lance un sous-processus ngrok (src/services/ngrok.service.ts) et affiche l’URL publique dans la bannière de démarrage :

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

Cette route est non authentifiée — toute personne ayant l’URL peut atteindre votre Anki, donc elle est moins sécurisée que le Tunnel. Préférez le Tunnel sauf si vous avez une raison spécifique de gérer votre propre point de terminaison ngrok. (Nécessite une installation globale de ngrok et un authtoken.)

L’indicateur --ngrok lance ngrok avec --host-header=rewrite, donc ngrok réécrit le Host en amont en localhost avant de transférer. Cela maintient les requêtes dans la liste d’autorisation d’hôtes en boucle locale (voir protection contre le rebinding DNS) sans avoir à ajouter le domaine public *.ngrok à ALLOWED_HOSTS. Si vous exécutez plutôt ngrok manuellement, utilisez le même indicateur — ngrok http --host-header=rewrite 3000 — sinon ngrok transfère le nom d’hôte public ngrok comme Host et le serveur le rejette avec 403.

Options CLI (tous les modes)

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

Mode lecture seule (tous les modes)

L’indicateur --read-only (ou READ_ONLY=true) bloque les modifications du contenu des notes, des paquets, des balises, des médias et des types de notes, ainsi que la reprogrammation manuelle des cartes. Lorsqu’il est activé :

Toutes les opérations de lecture fonctionnent normalement (parcourir les paquets, voir les cartes, rechercher des notes)
Ces modifications restent autorisées : évaluer une carte pendant la révision (rate_card), suspendre/ne plus suspendre des cartes (suspend, unsuspend), synchroniser avec AnkiWeb (sync), et les outils GUI qui naviguent dans les fenêtres d’Anki (guiBrowse, guiDeckOverview, …)
Les modifications de contenu sont bloquées (addNote, deleteNotes, createDeck, updateNoteFields, etc.) ; createDeck pour un paquet qui existe déjà réussit toujours, car rien n’est écrit
La reprogrammation manuelle est bloquée : forgetCards (réinitialiser comme nouveau) et setDueDate
guiUndo est bloqué, car une annulation peut revenir sur une modification de la collection
guiAddCards et guiEditNote sont bloqués, car une note ajoutée ou enregistrée dans la boîte de dialogue qu’ils ouvrent est écrite dans la collection
Utile pour explorer les données Anki sans modifications accidentelles de son contenu

# 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

Vous pouvez également activer le mode lecture seule via une variable d’environnement :

READ_ONLY=true ankimcp

Ou dans la configuration du client MCP :

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

Connect to Claude Desktop (mode local)

Vous pouvez configurer le serveur dans Claude Desktop soit :

En allant dans : Paramètres → Développeur → Modifier la configuration
Ou en modifiant manuellement le fichier de configuration

Configuration

Ajoutez ce qui suit à votre configuration Claude Desktop :

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

Remplacez /path/to/anki-mcp-server par votre chemin de projet réel.

Emplacements des fichiers de configuration

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

Pour plus de détails, voir la documentation officielle MCP.

Variables d’environnement (optionnelles)

Variable	Description	Défaut
`ANKI_CONNECT_URL`	URL AnkiConnect	`http://localhost:8765`
`ANKI_CONNECT_API_VERSION`	Version de l’API	`6`
`ANKI_CONNECT_API_KEY`	Clé API si configurée dans AnkiConnect	-
`ANKI_CONNECT_TIMEOUT`	Délai d’expiration de la requête en ms	`5000`
`READ_ONLY`	Activer le mode lecture seule (`true` ou `1`)	`false`
`PORT`	Mode HTTP : port d’écoute (l’indicateur `--port` a priorité)	`3000`
`HOST`	Mode HTTP : adresse à lier (l’indicateur `--host` a priorité)	`127.0.0.1`
`ALLOWED_HOSTS`	Mode HTTP : valeurs d’en-tête `Host` supplémentaires à accepter au-delà de la boucle locale (noms d’hôte séparés par des virgules). Requis lors de la liaison à une adresse LAN/publique ou derrière un proxy inverse. Voir Configuration du mode HTTP.	boucle locale uniquement
`ALLOWED_ORIGINS`	Mode HTTP : liste d’autorisation séparée par des virgules des modèles `Origin`/`Referer` du navigateur (les caractères génériques sont pris en charge, par ex. `https://*.ngrok.io`).	`http://localhost:,http://127.0.0.1:,https://localhost:,https://127.0.0.1:`
`TUNNEL_SERVER_URL`	URL WebSocket du serveur tunnel (mode tunnel uniquement)	`wss://tunnel.ankimcp.ai`
`MEDIA_ALLOWED_TYPES`	Types MIME supplémentaires à autoriser pour les importations de chemins de fichiers (séparés par des virgules, par ex. `application/pdf`)	-
`MEDIA_IMPORT_DIR`	Restreindre les importations de chemins de fichiers à ce répertoire	-
`MEDIA_ALLOWED_HOSTS`	Autoriser des hôtes de réseau privé spécifiques pour les importations d’URL (séparés par des virgules, par ex. `192.168.1.50,my-nas`)	-

Exemples d’utilisation

Recherche et mise à jour de notes

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

Exemples de syntaxe de requête Anki

L’outil findNotes prend en charge la puissante syntaxe de requête d’Anki :

"deck:DeckName" - Toutes les notes d'un paquet spécifique
"tag:important" - Notes avec le tag « important »
"is:due" - Cartes à réviser
"is:new" - Nouvelles cartes pas encore étudiées
"added:7" - Notes ajoutées au cours des 7 derniers jours
"front:hello" - Notes avec « hello » dans le champ recto
"flag:1" - Notes avec drapeau rouge
"prop:due<=2" - Cartes à réviser sous 2 jours
"deck:Spanish tag:verb" - Notes du paquet espagnol avec le tag verbe (ET)
"deck:Spanish OR deck:French" - Notes de l'un ou l'autre paquet

Remarques importantes

Gestion du CSS et du HTML

L'outil notesInfo renvoie le nom du type de note de chaque note ; le CSS lui-même provient de modelStyling
L'outil updateNoteFields prend en charge le contenu HTML dans les champs et préserve le style CSS
Chaque modèle de note possède son propre style CSS — utilisez modelStyling pour obtenir le CSS spécifique au modèle

Avertissement de mise à jour

⚠️ IMPORTANT : Lorsque vous utilisez updateNoteFields, ne visualisez PAS la note dans le navigateur d'Anki pendant la mise à jour, sinon les champs ne se mettront pas à jour correctement. Fermez le navigateur ou passez à une autre note avant de mettre à jour. Voir Problèmes connus pour plus de détails.

Sécurité de la suppression

L'outil deleteNotes exige une confirmation explicite (confirmDeletion: true) pour éviter les suppressions accidentelles. Supprimer une note supprime définitivement TOUTES les cartes associées.

Sécurité

Validation des chemins de fichiers et des URL de médias

Les outils média (storeMediaFile, retrieveMediaFile, deleteMediaFile) et les champs audio/image updateNoteFields incluent une validation de sécurité pour prévenir les abus par injection de prompt :

Les importations de chemins de fichiers sont limitées aux types de fichiers médias uniquement (images, audio, vidéo). Les fichiers non médias (par exemple, clés SSH, identifiants, configurations shell) sont rejetés en fonction du type MIME. Configurez MEDIA_ALLOWED_TYPES pour autoriser des types de fichiers supplémentaires, ou MEDIA_IMPORT_DIR pour restreindre les importations à un répertoire spécifique.
Les importations d'URL sont validées contre les attaques SSRF. Les requêtes vers les réseaux privés (10.x, 172.16.x, 192.168.x), loopback (127.x), link-local (169.254.x) et les schémas non-HTTP(S) sont bloquées. Configurez MEDIA_ALLOWED_HOSTS pour autoriser des hôtes de réseaux privés spécifiques.
Les noms de fichiers sont assainis pour empêcher le traversement de chemins (par exemple, les séquences ../../ sont supprimées).

Ces protections s'appliquent à storeMediaFile, retrieveMediaFile, deleteMediaFile et aux champs audio/image updateNoteFields.

Vulnérabilité de traversement de chemins signalée par Hideaki Takahashi.

Protection contre le DNS-rebinding (transport HTTP)

En mode HTTP, le serveur valide l'en-tête Host sur chaque requête. Par défaut, seuls les hôtes loopback (localhost, 127.0.0.1, ::1) sont acceptés, quel que soit le port. Host est un en-tête interdit aux navigateurs, donc une page web malveillante ne peut pas le falsifier — cela ferme la voie du DNS-rebinding où une page rebondie atteint le serveur local avec un Host usurpé et sans Origin, et atteint les outils MCP. Un Host non autorisé est rejeté avec 403.

Si vous vous liez à 0.0.0.0, exécutez derrière un proxy inverse ou exposez un domaine de tunnel public, définissez ALLOWED_HOSTS (noms d'hôtes séparés par des virgules) pour autoriser ces hôtes. Lors d'un tunnel avec ngrok, le serveur utilise --host-header=rewrite, donc l'amont voit toujours un Host en loopback. Voir Configuration du mode HTTP pour la liste complète des options.

Vulnérabilité de DNS-rebinding signalée par avishaigo-commits et yotampe-pluto.

Politique de confidentialité

Ce serveur MCP s'exécute localement sur votre machine et ne collecte aucune télémétrie, analytique ou donnée d'utilisation.

Politique complète : https://ankimcp.ai/privacy/

Collecte de données : Le serveur ne collecte rien. Il relaie les requêtes entre votre assistant IA et votre plugin AnkiConnect local.
Utilisation / stockage : Aucun stockage côté serveur. Toutes les données de cartes mémoire restent dans votre installation Anki sur votre propre appareil.
Partage avec des tiers : Aucun. Le serveur ne communique qu'avec l'URL AnkiConnect que vous configurez (par défaut : localhost). Si vous activez la synchronisation AnkiWeb intégrée d'Anki, elle se produit directement entre votre installation Anki et AnkiWeb — hors du périmètre de ce serveur.
Conservation : Non applicable — aucune donnée n'est conservée côté serveur.
Contact : support@ankimcp.ai

Problèmes connus

Pour une liste complète des problèmes connus et des limitations, veuillez consulter notre documentation :

Documentation des problèmes connus

Limitations critiques

Les mises à jour de notes échouent lorsqu'elles sont visualisées dans le navigateur

⚠️ IMPORTANT : Lors de la mise à jour de notes avec updateNoteFields, la mise à jour échoue silencieusement si la note est actuellement visualisée dans la fenêtre du navigateur d'Anki. Il s'agit d'une limitation en amont d'AnkiConnect.

Solution de contournement : Fermez toujours le navigateur ou naviguez vers une autre note avant de mettre à jour.

Pour plus de détails et d'autres problèmes connus, voir la documentation complète.

Dépannage

Erreur ERR_REQUIRE_ESM

Si vous voyez une erreur comme :

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

Cela signifie que votre version de Node.js n'est pas prise en charge. Le serveur nécessite Node.js 22.12.0+.

Remarque : Le runtime minimal pris en charge est Node.js 22.12.0. Node.js 20 (Iron) a atteint sa fin de vie le 2026-04-30 et n'est plus pris en charge.

Vérifiez votre version :

node --version

Solution : Mettez à jour Node.js vers la version 22.12.0+. Vous pouvez le télécharger depuis nodejs.org ou utiliser un gestionnaire de versions comme nvm.

Développement

Modes de transport

Ce serveur prend en charge trois modes de transport MCP via des points d'entrée séparés :

Mode STDIO (par défaut)

Pour les clients MCP locaux comme Claude Desktop
Utilise l'entrée/sortie standard pour la communication
Point d'entrée : dist/main-stdio.js
Exécution : npm run start:prod:stdio ou node dist/main-stdio.js
Bundle MCPB : Utilise le mode STDIO

Mode HTTP (HTTP streamable)

Pour les clients MCP distants et les intégrations web
Utilise le protocole MCP Streamable HTTP
Point d'entrée : dist/main-http.js
Exécution : npm run start:prod:http ou node dist/main-http.js
Port par défaut : 3000 (configurable via la variable d'environnement PORT)
Hôte par défaut : 127.0.0.1 (configurable via la variable d'environnement HOST)
Point de terminaison MCP : http://127.0.0.1:3000/ (chemin racine)

Mode Tunnel (tunnel WebSocket géré)

Pour les assistants IA web via le service de tunnel AnkiMCP géré, avec authentification intégrée
Le serveur MCP s'exécute en processus derrière un transport en mémoire ; TunnelTransport possède le serveur MCP et TunnelClient le relie au service de tunnel via un WebSocket
Protocole : sert uniquement la révision MCP 2025 (STDIO et HTTP servent également 2026-07-28)
Point d'entrée : dist/main-tunnel.js
Exécution : node dist/main-tunnel.js --tunnel (ou ankimcp --tunnel)
Authentification : ankimcp --login / ankimcp --logout ; identifiants stockés à ~/.ankimcp/credentials.json (0600)
Développement : npm run start:dev:tunnel (mode surveillance, exécute --tunnel --debug)

Construction

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

main-stdio.js, main-http.js et main-tunnel.js sont tous construits dans le même répertoire dist/. Choisissez lequel exécuter selon vos besoins.

Configuration du mode HTTP

Variables d'environnement :

PORT - Port du serveur HTTP (par défaut : 3000)
HOST - Adresse de liaison (par défaut : 127.0.0.1 pour localhost uniquement)
ALLOWED_HOSTS - Valeurs d'en-tête Host supplémentaires séparées par des virgules à accepter au-delà de l'ensemble loopback intégré (localhost, 127.0.0.1, ::1). Nom d'hôte uniquement et indépendant du port. Par défaut : loopback uniquement.
ALLOWED_ORIGINS - Liste blanche séparée par des virgules de modèles Origin/Referer de navigateur ; les caractères génériques sont pris en charge (par exemple https://*.ngrok.io). Par défaut : http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
LOG_LEVEL - Niveau de journalisation (par défaut : info)

Sécurité :

Validation de l'en-tête Host (protection contre le DNS-rebinding) — chaque requête HTTP doit porter un en-tête Host qui correspond à la liste blanche. Par défaut, seuls les hôtes loopback (localhost, 127.0.0.1, ::1) sont acceptés, quel que soit le port. Host est un en-tête interdit aux navigateurs, donc une page web malveillante ne peut pas le falsifier — cela ferme la voie du DNS-rebinding où une page rebondie atteint le serveur avec un Host usurpé et sans Origin. Un Host non autorisé est rejeté avec 403.
Validation de l'en-tête Origin — les requêtes de navigateur avec un Origin/Referer présent mais non autorisé sont rejetées. Les requêtes sans Origin (curl, Postman, clients MCP-over-HTTP) sont autorisées ; la validation Host est la défense contre le rebinding.
Se lie à localhost (127.0.0.1) par défaut.
Aucune authentification dans la version actuelle (prise en charge OAuth prévue).

Exposition du mode HTTP au-delà de localhost — si vous vous liez à une adresse LAN/publique ou placez le serveur derrière un proxy inverse ou un domaine public, vous devez définir ALLOWED_HOSTS sur le(s) nom(s) d'hôte(s) que les clients utiliseront, sinon chaque requête non-loopback est rejetée avec 403 :

# 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

Lorsque vous vous liez à 0.0.0.0/:: sans ALLOWED_HOSTS, le serveur journalise un avertissement de démarrage indiquant que seuls les en-têtes Host en loopback seront acceptés.

Docker / proxy inverse / domaine public : la même règle s'applique. Dans Docker, les requêtes arrivent généralement avec le nom d'hôte publié du conteneur ou le Host du proxy, donc définissez ALLOWED_HOSTS en conséquence. Un proxy inverse (nginx, Caddy, Traefik) doit soit transmettre le Host d'origine et avoir ce nom d'hôte listé dans ALLOWED_HOSTS, soit réécrire le Host en amont vers localhost. L'intégration intégrée --ngrok gère cela automatiquement (voir ci-dessous).

Exemple : Modes d'exécution

# 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

Construction d'un bundle MCPB

Pour créer un bundle MCPB distribuable :

npm run mcpb:bundle

Cette commande va :

Synchroniser la version de package.json vers manifest.json
Supprimer les anciens fichiers .mcpb
Construire le projet TypeScript
Empaqueter dist/ et node_modules/ dans un fichier .mcpb
Exécuter mcpb clean pour supprimer les devDependencies (optimise le bundle de ~47 Mo à ~10 Mo)

Le fichier de sortie sera nommé anki-mcp-server-X.X.X.mcpb et pourra être distribué pour une installation en un clic.

Ce qui est inclus dans le bundle

Le bundle MCPB comprend :

JavaScript compilé (répertoire dist/ - inclut les trois points d'entrée)
Dépendances de production uniquement (node_modules/ - devDependencies supprimées par mcpb clean)
Métadonnées du paquet (package.json)
Configuration du manifeste (manifest.json - configuré pour utiliser main-stdio.js)
Icône (icon.png)

Les fichiers sources, les tests et les configurations de développement sont automatiquement exclus via .mcpbignore.

Journalisation dans Claude Desktop

Lorsqu'il est exécuté comme extension MCPB dans Claude Desktop, les journaux sont écrits dans :

Emplacement des journaux : ~/Library/Logs/Claude/ (macOS)

Les journaux sont répartis sur plusieurs fichiers :

main.log - Journaux généraux de l'application Claude Desktop
mcp-server-Anki MCP Server.log - Messages du protocole MCP pour cette extension
mcp.log - Journaux MCP combinés de tous les serveurs

Remarque : La sortie du journaliseur pino (messages INFO, ERROR, WARN du code serveur) va vers stderr et apparaît dans les fichiers journaux spécifiques au MCP. Claude Desktop détermine quel fichier journal reçoit quels messages, mais en général :

Démarrage de l'application et communication du protocole MCP → journal spécifique au MCP
Journalisation interne du serveur (pino) → à la fois le journal spécifique au MCP et parfois main.log

Pour afficher les journaux en temps réel :

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

Débogage du serveur MCP

Vous pouvez déboguer le serveur MCP à l'aide de l'inspecteur MCP et en attachant un débogueur depuis votre IDE (WebStorm, VS Code, etc.).

Remarque pour le mode HTTP : Lors du test du mode HTTP (Streamable HTTP) avec l'inspecteur MCP, utilisez « Type de connexion : Via proxy » pour éviter les erreurs CORS.

Étape 1 : Configurer le serveur de débogage dans l'inspecteur MCP

Le mcp-inspector-config.json inclut déjà une configuration de serveur de débogage :

{
  "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"
    }
  }
}

Étape 2 : Démarrer le serveur de débogage

Exécutez l'Inspector MCP avec le serveur de débogage :

npm run inspector:debug

Cela démarrera le serveur avec le débogage Node.js activé sur le port 9229 et mettra l'exécution en pause à la première ligne.

Étape 3 : Attacher le débogueur depuis votre IDE

WebStorm

Allez dans Run → Edit Configurations
Ajoutez une nouvelle configuration Attach to Node.js/Chrome
Définissez le port sur 9229
Cliquez sur Debug pour attacher

VS Code

Ouvrez le panneau Debug (Ctrl+Shift+D / Cmd+Shift+D)
Sélectionnez la configuration Debug MCP Server (Attach)
Appuyez sur F5 pour attacher

Étape 4 : Définir des points d'arrêt et déboguer

Une fois attaché, vous pouvez :

Définir des points d'arrêt dans vos fichiers source TypeScript
Parcourir l'exécution du code pas à pas
Inspecter les variables et la pile d'appels
Utiliser la console de débogage pour évaluer des expressions

Le débogueur fonctionnera avec les source maps, vous permettant de déboguer le code TypeScript d'origine plutôt que le JavaScript compilé.

Débogage avec Claude Desktop

Vous pouvez également déboguer le serveur MCP pendant qu'il s'exécute dans Claude Desktop en activant le débogueur Node.js et en attachant votre IDE.

Étape 1 : Configurer Claude Desktop pour le débogage

Mettez à jour la configuration de Claude Desktop pour activer le débogage :

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"
      }
    }
  }
}

Changement clé : Ajoutez --inspect=9229 avant le chemin vers dist/main-stdio.js

Options de débogage :

--inspect=9229 - Démarre le débogueur immédiatement, ne bloque pas (recommandé)
--inspect-brk=9229 - Met l'exécution en pause jusqu'à ce que le débogueur s'attache (pour déboguer les problèmes de démarrage)

Étape 2 : Redémarrer Claude Desktop

Après avoir enregistré la configuration, redémarrez Claude Desktop. Le serveur MCP s'exécutera désormais avec le débogage activé sur le port 9229.

Étape 3 : Attacher le débogueur depuis votre IDE

WebStorm

Allez dans Run → Edit Configurations
Cliquez sur le bouton + et sélectionnez Attach to Node.js/Chrome
Configurez :
- Name : Attach to Anki MCP (Claude Desktop)
- Host : localhost
- Port : 9229
- Attach to : Node.js < 8 ou Chrome or Node.js > 6.3 (selon la version de WebStorm)
Cliquez sur OK
Cliquez sur Debug (Shift+F9) pour attacher

VS Code

Ajoutez à .vscode/launch.json :

{
  "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"]
    }
  ]
}

Ouvrez le panneau Debug (Ctrl+Shift+D / Cmd+Shift+D)
Sélectionnez Attach to Anki MCP (Claude Desktop)
Appuyez sur F5 pour attacher

Étape 4 : Déboguer en temps réel

Une fois attaché, vous pouvez :

Définir des points d'arrêt dans vos fichiers source TypeScript (par exemple, src/mcp/primitives/essential/tools/create-model.tool.ts)
Utiliser Claude Desktop normalement - les points d'arrêt seront atteints lorsque les outils seront invoqués
Parcourir l'exécution du code pas à pas
Inspecter les variables et la pile d'appels
Utiliser la console de débogage

Exemple : Définissez un point d'arrêt dans create-model.tool.ts à la ligne 119, puis demandez à Claude de créer un nouveau modèle. Le débogueur s'arrêtera à votre point d'arrêt !

Remarque : Le débogueur reste attaché tant que Claude Desktop est en cours d'exécution. Vous pouvez détacher/rattacher à tout moment sans redémarrer Claude Desktop.

Commandes de construction

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

Test du paquet NPM (local)

Testez le paquet npm localement avant de le publier :

# 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

Comment cela fonctionne :

npm pack crée un fichier .tgz identique à ce que npm publish créerait
L'installation depuis .tgz simule ce que les utilisateurs obtiennent depuis npm install -g ankimcp
Cela vous permet de tester l'expérience utilisateur complète avant de publier sur npm

Commandes de test

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)

Couverture des tests

Le projet maintient des seuils de couverture minimaux de 70 % pour :

Les branches
Les fonctions
Les lignes
Les instructions

Les rapports de couverture sont générés dans le répertoire coverage/.

Versionnage

Ce projet suit la gestion sémantique de version avec une approche de développement pré-1.0 :

0.x.x - Versions bêta/développement (phase actuelle)
- 0.1.x - Corrections de bugs et correctifs
- 0.2.0+ - Nouvelles fonctionnalités ou améliorations mineures
- Les changements cassants sont acceptables dans les versions 0.x
1.0.0 - Première version stable
- Sera publiée lorsque l'API sera stable et testée
- Les changements cassants nécessiteront des augmentations de version majeure (2.0.0, etc.)

Statut actuel : 0.27.0 - Développement bêta actif. Les fonctionnalités récentes incluent l'analyse de révision à l'échelle de la collection (review_stats agrège désormais tous les jeux de cartes lorsque deck est omis), la gestion des champs de modèle (addModelField, removeModelField, renameModelField, repositionModelField), la création de notes par lots (addNotes), le tunneling ngrok intégré (indicateur --ngrok), la gestion des fichiers média, la gestion des modèles/modèles, et des statistiques complètes de jeux de cartes. Les API peuvent changer en fonction des retours et des tests.

Évolution de la spécification MCPB

Ce projet cible la spécification de bundle MCPB d'Anthropic, qui est encore en évolution. Nous suivons la spécification sur https://github.com/modelcontextprotocol/mcpb et pouvons introduire des changements cassants pour rester conformes. Les changements cassants sont autorisés dans le schéma de versionnage 0.x.x.

Projets similaires

Si vous explorez les intégrations Anki MCP, voici d'autres projets dans cet espace :

scorzeth/anki-mcp-server

Statut : Semble abandonné (aucune mise à jour récente)
Implémentation précoce de l'intégration Anki MCP

nailuoGG/anki-mcp-server

Approche : Implémentation légère et monofichier
Architecture : Structure de code procédurale avec tous les outils dans un seul fichier
Bon pour : Cas d'utilisation simples, dépendances minimales

Pourquoi ce projet diffère :

Architecture de niveau entreprise : Construit sur NestJS avec injection de dépendances
Conception modulaire : Chaque outil est une classe séparée avec une séparation claire des préoccupations
Maintenabilité : Facile à étendre avec de nouvelles fonctionnalités sans toucher au code existant
Tests : Suite de tests complète avec exigence de couverture de 70 %
Sécurité des types : TypeScript strict avec validation Zod
Gestion des erreurs : Gestion robuste des erreurs avec retour utilisateur utile
Prêt pour la production : Journalisation appropriée, rapport de progression et prise en charge du bundle MCPB
Évolutivité : Peut facilement passer d'outils de base à des flux de travail complexes

Cas d'utilisation : Si vous avez besoin d'une base solide pour construire des intégrations Anki avancées ou prévoyez d'étendre considérablement les fonctionnalités, l'approche architecturale de ce projet facilite la maintenance et l'évolution dans le temps.

Liens utiles

Licence et attribution

Ce projet est sous licence MIT — voir LICENSE pour le texte complet.

Attributions tierces

Anki® est une marque déposée d'Ankitects Pty Ltd. Ce projet est un outil tiers non officiel et n'est pas affilié à, approuvé par, ou sponsorisé par Ankitects Pty Ltd. Le logo Anki est utilisé sous la licence alternative pour référencer Anki avec un lien vers https://apps.ankiweb.net. Pour l'application officielle Anki, visitez https://apps.ankiweb.net.
Model Context Protocol (MCP) est un standard ouvert d'Anthropic. Le logo MCP provient du dépôt officiel de documentation MCP et est utilisé sous la licence MIT. Pour plus d'informations sur MCP, visitez https://modelcontextprotocol.io.
Ceci est un projet indépendant qui relie les technologies Anki et MCP. Toutes les marques, marques de service, noms commerciaux, noms de produits et logos sont la propriété de leurs propriétaires respectifs.