Anki MCP

oficial

Un servidor MCP que permite a los asistentes de IA interactuar con Anki, la aplicación de tarjetas de memoria con repetición espaciada.

GitHub

539

¿Qué puedes hacer con Anki MCP?

Revisar tarjetas pendientes — Pídele a tu asistente que recupere las tarjetas pendientes de un mazo específico y te las presente en formato de cuestionario con get_due_cards y present_card.
Calificar el rendimiento de las tarjetas — Haz que el asistente registre la calidad de tu respuesta (Otra vez, Difícil, Bien, Fácil) para reprogramar las revisiones mediante rate_card.
Crear tarjetas personalizadas — Indícale al asistente que cree nuevos tipos de notas con campos personalizados y estilo RTL usando createModel y updateModelStyling, y luego agregue notas en lote con addNotes.
Gestionar el contenido de las notas — Busca notas con la sintaxis de consulta de Anki (deck:, tag:, is:due) mediante findNotes, y luego actualiza sus campos con updateNoteFields.
Importar medios en las tarjetas — Pídele al asistente que suba una imagen desde una ruta local o URL con storeMediaFile y la inserte en el campo de una nota seleccionada usando guiSelectedNotes y updateNoteFields.
Organizar mazos y tarjetas — Crea mazos anidados (Parent::Child) con createDeck, mueve tarjetas entre mazos con changeDeck, o suspende tarjetas con suspend para omitirlas durante la revisión.

Documentación

Servidor Anki MCP

Integra perfectamente Anki con asistentes de IA a través del Protocolo de Contexto de Modelo

[!IMPORTANT] Prefiere el complemento AnkiMCP para la mayoría de las configuraciones.

El complemento (GitHub) ejecuta el servidor MCP directamente dentro de Anki. No hay Node.js que instalar, ni AnkiConnect que configurar, ni proceso separado que mantener en ejecución: instálalo con el código 124672614, reinicia Anki, y el servidor estará activo cada vez que Anki se abra. Cubre acceso HTTP local y acceso remoto a través de un túnel integrado.

Este repositorio es la opción correcta cuando necesitas específicamente:

Transporte STDIO — Claude Desktop, Claude Code, Cursor, o cualquier cliente que inicie el servidor como subproceso

Paquete MCPB — la instalación de un clic .mcpb para Claude Desktop

Para HTTP, túnel, o clientes basados en web (claude.ai, ChatGPT), el complemento es la vía más simple y mejor soportada.

Este repositorio no está en desuso. Se mantiene actualizado y se publica junto con el complemento como parte del mismo proyecto ankimcp.ai.

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con Anki, la aplicación de tarjetas de repetición espaciada.

Transforma tu experiencia con Anki mediante interacción en lenguaje natural, como tener un tutor privado. El asistente de IA no solo presenta preguntas y respuestas; puede explicar conceptos, hacer el proceso de aprendizaje más atractivo y humano, proporcionar contexto y adaptarse a tu estilo de aprendizaje. Puede crear y editar notas sobre la marcha, convirtiendo tus sesiones de estudio en conversaciones dinámicas. ¡Más funciones próximamente!

Ejemplos y Tutoriales

Para guías completas, ejemplos del mundo real y tutoriales paso a paso sobre el uso de este servidor MCP con Claude Desktop, visita:

ankimcp.ai - Documentación completa con ejemplos prácticos y casos de uso

Consulta docs/ para documentación complementaria, incluida la guía de configuración del revisor y el mazo de Anki de muestra.

Casos de Uso de Ejemplo

Tres indicaciones representativas que muestran los flujos de herramientas que este servidor habilita:

"Ayúdame a repasar mi mazo de español." — El asistente ofrece sincronizar con AnkiWeb (sync), obtiene las tarjetas pendientes (get_due_cards con filtro de mazo), presenta cada tarjeta (present_card) y registra tu calificación (rate_card). Conversación de estudio natural con explicaciones adaptadas a ti.
"Crea 10 tarjetas de vocabulario árabe con estilo RTL." — El asistente lista los tipos de nota (modelNames), crea un modelo RTL personalizado si es necesario (createModel + updateModelStyling para CSS de derecha a izquierda), y luego crea las tarjetas en lote (addNotes).
"Importa esta imagen de mi carpeta de Descargas al frente de la nota seleccionada." — El asistente sube el archivo local (storeMediaFile con una ruta de archivo), lee la nota actualmente seleccionada del navegador (guiSelectedNotes + notesInfo) y actualiza el campo frontal con una etiqueta <img> (updateNoteFields).

Herramientas Disponibles

El servidor expone 53 herramientas MCP — 42 herramientas esenciales para operaciones diarias de Anki y 11 herramientas GUI que controlan la interfaz de escritorio de Anki para flujos de edición/creación de notas.

Herramientas Esenciales

Revisión y Estudio

sync - Sincroniza con AnkiWeb para obtener los últimos datos y enviar cambios
get_due_cards - Obtiene tarjetas pendientes de revisión, opcionalmente filtradas por mazo (respuestas omitidas a menos que include_answer: true, por defecto false)
get_cards - Obtiene tarjetas con filtrado flexible por estado (pendiente, nueva, en aprendizaje, suspendida, enterrada) y mazo (respuestas omitidas a menos que include_answer: true, por defecto false)
present_card - Muestra una tarjeta para revisión con su pregunta/cara frontal
rate_card - Califica el rendimiento de la tarjeta (Otra vez, Difícil, Bien, Fácil) y programa la próxima revisión
forgetCards - Restablece tarjetas a nuevas, descartando su programación sin registrar una revisión
setDueDate - Reprograma tarjetas para que venzan en N días ("0", "3-7", "1!"), sin registrar una revisión
areSuspended - Verifica el estado de suspensión de una o más tarjetas sin cambiar nada
suspend - Suspende tarjetas para que se omitan durante la revisión hasta que se desuspenda
unsuspend - Desuspende tarjetas para que vuelvan a la revisión normal

Nota: forgetCards y setDueDate cambian la programación sin registrar una revisión, que es lo que las separa de rate_card. Úsalas cuando la programación de una tarjeta sea incorrecta en lugar de la respuesta: calificar una tarjeta Again para enterrarla más profundo registra un fallo real y reduce su factor de facilidad, sesgando permanentemente tanto la programación futura como tus estadísticas. forgetCards borra el intervalo y comienza la tarjeta de nuevo; setDueDate conserva el historial de la tarjeta y solo mueve la próxima revisión.

Nota: El contenido de las tarjetas front/back se renderiza por tarjeta según su propia plantilla (como Anki lo muestra), por lo que las tarjetas invertidas y de texto oculto muestran la dirección correcta. El texto estático añadido por tus plantillas de tarjeta también aparece en la salida.

Gestión de Mazos

listDecks - Lista todos los mazos, opcionalmente con estadísticas de cola de estudio por mazo
deckStats - Obtiene estadísticas completas para un solo mazo (cola de estudio, conteos reales de estado de tarjetas, distribuciones de facilidad/intervalo)
createDeck - Crea un nuevo mazo vacío (soporta Parent::Child, máximo 2 niveles)
changeDeck - Mueve tarjetas a un mazo diferente (se crea si no existe)

Nota: Las estadísticas de mazo vienen en dos variantes. El bloque counts (y todo lo que listDecks reporta) refleja el navegador de mazos de Anki: tarjetas pendientes hoy, limitadas por los límites diarios de nuevas/revisiones de cada mazo, con tarjetas suspendidas y enterradas excluidas — por lo que review no es "tarjetas maduras" y el grupo other es solo el resto aritmético (principalmente tarjetas de revisión no pendientes hoy más tarjetas nuevas sobre el límite diario). Para totales reales por estado usa el bloque states en deckStats / collection_stats, que cuenta new, learning, review, suspended y buried mediante búsquedas de Anki, ignorando fechas de vencimiento y límites diarios.

Gestión de Notas

addNote - Crea una sola nota con campos y etiquetas especificados
addNotes - Crea en lote hasta 100 notas que comparten mazo y modelo (soporta éxito parcial)
findNotes - Busca notas usando la sintaxis de consulta de Anki (deck:, tag:, is:due, etc.)
notesInfo - Obtiene información detallada sobre notas (campos, etiquetas, tipo de nota, IDs de tarjetas; el CSS proviene de modelStyling)
updateNoteFields - Actualiza campos de notas existentes (consciente de CSS, soporta contenido HTML)
deleteNotes - Elimina notas y todas las tarjetas asociadas (destructivo, requiere confirmación)

Gestión de Etiquetas

getTags - Obtiene todas las etiquetas de la colección (usa la primera para evitar duplicación)
addTags - Añade etiquetas separadas por espacios a notas especificadas
removeTags - Elimina etiquetas separadas por espacios de notas especificadas
replaceTags - Renombra una etiqueta en notas especificadas
clearUnusedTags - Elimina etiquetas huérfanas no usadas por ninguna nota (destructivo)

Gestión de Medios

getMediaFilesNames - Lista archivos de medios en collection.media, opcionalmente filtrados por patrón
retrieveMediaFile - Descarga un archivo de medios como contenido base64
storeMediaFile - Sube medios desde datos base64, una ruta de archivo absoluta o una URL
deleteMediaFile - Elimina un archivo de medios de collection.media (destructivo)

💡 Mejor Práctica para Imágenes:

✅ Usa rutas de archivo (p. ej., /Users/you/image.png) - Rápido y eficiente
✅ Usa URLs (p. ej., https://example.com/image.jpg) - Descarga directa
❌ Evita base64 - Extremadamente lento e ineficiente en tokens

Solo dile a Claude dónde está la imagen, y manejará la subida automáticamente usando el método más eficiente.

Gestión de Modelos/Plantillas

modelNames - Lista todos los tipos de nota/modelos disponibles
modelFieldNames - Obtiene los nombres de campos para un tipo de nota específico
modelStyling - Obtiene la información de estilo CSS para un tipo de nota
modelTemplates - Obtiene las plantillas de tarjeta (HTML Frontal y Trasero) para un tipo de nota
createModel - Crea un nuevo tipo de nota con campos personalizados, plantillas de tarjeta y CSS (p. ej., modelos RTL)
updateModelStyling - Actualiza el estilo CSS para un tipo de nota existente (se aplica a todas sus tarjetas)
updateModelTemplates - Actualiza las plantillas de tarjeta (HTML Frontal y Trasero) para un tipo de nota existente (se aplica a todas sus tarjetas)
addModelField - Añade un nuevo campo a un tipo de nota existente (se añade al final o se inserta en una posición específica)
removeModelField - Elimina un campo de un tipo de nota existente (borra su contenido de todas las notas; requiere confirmación explícita)
renameModelField - Renombra un campo en un tipo de nota existente (Anki reescribe las referencias al nombre antiguo en las plantillas de tarjeta)
repositionModelField - Cambia la posición de un campo dentro de un tipo de nota existente

Estadísticas

collection_stats - Estadísticas agregadas en todos los mazos con desglose por mazo y conteos de estado de tarjetas en toda la colección
review_stats - Análisis del historial de revisiones (patrones temporales, métricas de retención, rachas de estudio)

Herramientas GUI

Herramientas que controlan la interfaz de escritorio de Anki. Destinadas a flujos de edición/creación de notas y gestión de mazos, no para sesiones de revisión.

guiBrowse - Abre el Navegador de Tarjetas y busca tarjetas
guiSelectCard - Selecciona una tarjeta específica en el Navegador de Tarjetas
guiSelectedNotes - Obtiene los IDs de las notas actualmente seleccionadas en el Navegador de Tarjetas
guiAddCards - Abre el diálogo Añadir Tarjetas con detalles de nota preestablecidos
guiEditNote - Abre el editor de notas para una nota específica
guiDeckOverview - Abre el diálogo de Resumen del Mazo para un mazo específico
guiDeckBrowser - Abre el diálogo del Navegador de Mazos
guiCurrentCard - Obtiene información sobre la tarjeta actual en modo de revisión (incluye la respuesta; da error fuera del modo de revisión)
guiShowQuestion - Muestra el lado de la pregunta de la tarjeta actual
guiShowAnswer - Muestra el lado de la respuesta de la tarjeta actual
guiUndo - Deshace la última acción en Anki

Requisitos Previos

Anki con el complemento AnkiConnect instalado
Node.js 22.12.0+

Instalación

Hay varias formas de instalar el servidor en tu máquina. Una vez instalado, dirígete a Conectando un Cliente de IA para conectarlo a tu asistente de IA — local o remotamente.

npm (global o npx)

La forma de propósito general de instalar el servidor, adecuada para cualquier cliente MCP que lo inicie directamente.

Instálalo globalmente para clientes que ejecutan el comando ankimcp:

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

O ejecútalo bajo demanda sin necesidad de instalación:

npx @ankimcp/anki-mcp-server

Paquete MCPB (Recomendado para Claude Desktop)

La forma más fácil de instalar este servidor MCP para Claude Desktop:

Descarga el último paquete .mcpb de la página de Lanzamientos
En Claude Desktop, instala la extensión:
- Método 1: Ve a Configuración → Extensiones, luego arrastra y suelta el archivo .mcpb
- Método 2: Ve a Configuración → Desarrollador → Extensiones → Instalar Extensión, luego selecciona el archivo .mcpb
Configura la URL de AnkiConnect si es necesario (por defecto http://localhost:8765)
Reinicia Claude Desktop

¡Eso es todo! El paquete incluye todo lo necesario para ejecutar el servidor localmente.

Para revisores del Directorio MCP de Anthropic: un recorrido de cero a integración con un mazo de muestra precargado está en docs/reviewer-setup.md.

Instalar desde el Código Fuente (para desarrollo)

Para desarrollo o uso avanzado (ejecutar la suite de pruebas requiere Node.js 24.9+ — los scripts de prueba de npm cargan los paquetes NestJS 12 solo-ESM vía require(esm), que Jest solo soporta allí; el requisito de tiempo de ejecución para usar el servidor sigue siendo 22.12.0+):

npm install
npm run build

Conectando un Cliente de IA

Hay dos formas en que un asistente de IA puede alcanzar este servidor, dependiendo de dónde se ejecute el asistente:

Local — el servidor se ejecuta en la misma máquina que el cliente de IA (Claude Desktop, Cursor, Cline, Zed, o una sesión de navegador local). Usa STDIO para clientes MCP de escritorio, HTTP para herramientas web locales.
Remoto — una IA alojada/remota (p. ej. ChatGPT o Claude.ai en la nube) necesita alcanzar el Anki que se ejecuta en tu máquina local. Usa el Túnel gestionado (✅ recomendado — autenticado) o, como alternativa no autenticada más ligera, ngrok.

Local

El servidor se ejecuta en la misma computadora que tu cliente de IA y se comunica con AnkiConnect en localhost.

STDIO (integración local principal)

STDIO es el transporte estándar para clientes MCP de escritorio locales — Claude Desktop, Cursor IDE, Cline, Zed Editor, opencode, y otros. El cliente lanza el servidor como un subproceso y se comunica a través de entrada/salida estándar.

Clientes soportados:

Claude Desktop
Cursor IDE - Editor de código impulsado por IA
Cline - Extensión de VS Code para asistencia de IA
Zed Editor - Editor de código rápido y moderno
opencode - Agente de codificación de IA para terminal
Otros clientes MCP que soporten transporte STDIO

Para Claude Desktop, el paquete MCPB es la ruta más fácil. Para otros clientes, configura el paquete npm con la bandera --stdio.

Configuración - Elige un método:

Método 1: Usando npx (recomendado - no requiere instalación)

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

Método 2: Usando instalación global

Primero, instala globalmente:

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

Luego configura:

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

opencode usa su propio formato — los servidores van bajo mcp, el comando es un solo arreglo, y las variables de entorno van bajo 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"
      }
    }
  }
}

Ubicaciones de archivos de configuración:

Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) o %USERPROFILE%\.cursor\mcp.json (Windows)
Cline: Accesible a través de la interfaz de configuración en VS Code
Zed Editor: Instalar como extensión MCP a través del mercado de extensiones
opencode: opencode.json en la raíz de tu proyecto, o ~/.config/opencode/opencode.json globalmente

Para características específicas del cliente y solución de problemas, consulta la documentación de tu cliente MCP. Consulta también Conectar a Claude Desktop para una configuración que apunte directamente a un dist/main-stdio.js compilado.

HTTP (IA web local)

El modo HTTP ejecuta el servidor como un servidor web local que habla el protocolo MCP Streamable HTTP. Es el transporte con el que una herramienta de IA basada en web se comunica cuando apunta a tu máquina, y también es lo que las opciones Remoto exponen al mundo exterior. Por sí solo, el modo HTTP se vincula solo a localhost.

¿Vinculación más allá de localhost? Si pasas --host 0.0.0.0 (o ejecutas detrás de un proxy inverso/dominio público), el servidor solo acepta encabezados Host de loopback por defecto para protección contra rebinding de DNS — establece ALLOWED_HOSTS a los nombres de host que usan los clientes. Consulta Configuración del Modo HTTP.

Configuración - Elige un método:

Método 1: Usando npx (recomendado - no requiere instalación)

# 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étodo 2: Usando instalación global

# 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étodo 3: Instalar desde el código fuente (para desarrollo)

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

Para hacer que un servidor HTTP local sea alcanzable por una IA alojada en la nube, usa una de las opciones Remoto a continuación.

Remoto

Una IA alojada/remota (como ChatGPT o Claude.ai ejecutándose en la nube) no puede alcanzar localhost directamente. Estas opciones exponen tu Anki local a internet para que un asistente remoto pueda comunicarse con él.

Túnel (✅ Recomendado)

Ruta remota recomendada — autenticada y segura. A diferencia de un puerto público crudo, el modo túnel requiere que inicies sesión (flujo de dispositivo OAuth 2.0), por lo que el endpoint no está abierto a cualquiera que adivine la URL.

El modo túnel permite que asistentes de IA basados en web alcancen tu Anki local sin ejecutar tu propio túnel. El servidor se conecta al servicio de túnel gestionado de AnkiMCP (wss://tunnel.ankimcp.ai) a través de un WebSocket y se le asigna una URL pública. La autenticación está integrada — no se requiere cuenta de ngrok ni proceso de túnel separado, e inicias sesión una vez.

Iniciar sesión (flujo de dispositivo OAuth):

El modo túnel usa la Concesión de Autorización de Dispositivo OAuth 2.0. Iniciar sesión abre tu navegador automáticamente a una página de aprobación con el código ya incrustado en la URL — nada que escribir, solo aprobar. (Si el navegador no puede abrirse, la terminal imprime una URL de verificación y un código para ingresar manualmente como respaldo.) Al tener éxito, las credenciales se guardan en ~/.ankimcp/credentials.json (permisos de archivo 0600).

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

# Clear saved credentials
ankimcp --logout

Iniciar el túnel:

# 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 no existen credenciales, --tunnel inicia automáticamente el flujo de inicio de sesión primero, luego continúa al túnel. Este inicio de sesión automático requiere una terminal interactiva — cuando stdout no es un TTY (systemd, Docker sin cabeza, CI), el servidor falla rápidamente y te pide ejecutar ankimcp --login primero. Una vez conectado, se imprime la URL pública del túnel; presiona Ctrl+C para desconectar. Comparte esa URL con tu asistente de IA.

Variables de entorno del modo túnel:

Variable	Descripción	Predeterminado
`TUNNEL_SERVER_URL`	URL del WebSocket del servidor de túnel (el valor de la bandera `--tunnel`/`--login` anula esto)	`wss://tunnel.ankimcp.ai`
`TUNNEL_AUTH_CLIENT_ID`	ID de cliente OAuth para el flujo de dispositivo. Avanzado — solo necesario al apuntar a un servicio de túnel/auth autoalojado.	(integrado)

Los endpoints de autenticación del flujo de dispositivo (/auth/device, /auth/token) se derivan de TUNNEL_SERVER_URL, por lo que apuntar --tunnel (o TUNNEL_SERVER_URL) a un host diferente también mueve la autenticación a ese host.

Cómo funciona: El modo túnel ejecuta el servidor MCP en proceso detrás de un transporte en memoria (TunnelTransport). Ese transporte posee el servidor MCP y convierte cada cuerpo de solicitud retransmitido en una respuesta, y TunnelClient lo conecta al servicio de túnel remoto a través de un WebSocket — retransmitiendo solicitudes MCP hacia adentro y respuestas hacia afuera. AnkiConnect todavía solo se alcanza en tu máquina local.

Revisiones de protocolo: Debido a que el túnel conecta el servidor MCP en proceso, el modo túnel sirve solo la revisión 2025 del protocolo MCP, mientras que los modos STDIO y HTTP sirven tanto 2025 como la revisión más nueva 2026-07-28. Cada herramienta se comporta igual de cualquier manera — pero un cliente que solo habla 2026-07-28 es rechazado a través del túnel con un error de versión de protocolo; ejecuta el modo STDIO o HTTP para ese cliente.

ngrok (alternativa no autenticada)

Si prefieres exponer el modo HTTP local públicamente sin una cuenta en el túnel gestionado, la bandera integrada --ngrok lanza un subproceso de ngrok (src/services/ngrok.service.ts) e imprime la URL pública en el banner de inicio:

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

Esta ruta es no autenticada — cualquiera con la URL puede alcanzar tu Anki, por lo que es menos segura que Túnel. Prefiere Túnel a menos que tengas una razón específica para gestionar tu propio endpoint de ngrok. (Requiere una instalación global de ngrok y authtoken.)

La bandera --ngrok lanza ngrok con --host-header=rewrite, por lo que ngrok reescribe el Host ascendente a localhost antes de reenviar. Eso mantiene las solicitudes dentro de la lista de permitidos de Host de loopback (consulta protección contra rebinding de DNS) sin que tengas que agregar el dominio público *.ngrok a ALLOWED_HOSTS. Si en su lugar ejecutas ngrok manualmente, usa la misma bandera — ngrok http --host-header=rewrite 3000 — de lo contrario ngrok reenvía el nombre de host público de ngrok como Host y el servidor lo rechaza con 403.

Opciones de CLI (todos los modos)

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

Modo de Solo Lectura (todos los modos)

La bandera --read-only (o READ_ONLY=true) bloquea cambios al contenido de notas, mazos, etiquetas, medios y tipos de notas, y reprogramación manual de tarjetas. Cuando está habilitado:

Todas las operaciones de lectura funcionan normalmente (navegar mazos, ver tarjetas, buscar notas)
Estos cambios todavía están permitidos: calificar una tarjeta durante la revisión (rate_card), suspender/no suspender tarjetas (suspend, unsuspend), sincronizar con AnkiWeb (sync), y las herramientas de GUI que navegan las ventanas de Anki (guiBrowse, guiDeckOverview, …)
Las modificaciones de contenido están bloqueadas (addNote, deleteNotes, createDeck, updateNoteFields, etc.); createDeck para un mazo que ya existe todavía tiene éxito, ya que nada se escribe
La reprogramación manual está bloqueada: forgetCards (restablecer a nuevo) y setDueDate
guiUndo está bloqueado, ya que un deshacer puede revertir un cambio a la colección
guiAddCards y guiEditNote están bloqueados, ya que una nota agregada o guardada en el diálogo que abren se escribe en la colección
Útil para explorar datos de Anki sin cambios accidentales a su contenido

# 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

También puedes habilitar el modo de solo lectura a través de una variable de entorno:

READ_ONLY=true ankimcp

O en la configuración del cliente MCP:

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

Conectar a Claude Desktop (Modo Local)

Puedes configurar el servidor en Claude Desktop ya sea:

Yendo a: Configuración → Desarrollador → Editar Config
O editando manualmente el archivo de configuración

Configuración

Agrega lo siguiente a tu configuración de Claude Desktop:

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

Reemplaza /path/to/anki-mcp-server con tu ruta real del proyecto.

Ubicaciones de Archivos de Configuración

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

Para más detalles, consulta la documentación oficial de MCP.

Variables de Entorno (Opcional)

Variable	Descripción	Predeterminado
`ANKI_CONNECT_URL`	URL de AnkiConnect	`http://localhost:8765`
`ANKI_CONNECT_API_VERSION`	Versión de API	`6`
`ANKI_CONNECT_API_KEY`	Clave de API si está configurada en AnkiConnect	-
`ANKI_CONNECT_TIMEOUT`	Tiempo de espera de solicitud en ms	`5000`
`READ_ONLY`	Habilitar modo de solo lectura (`true` o `1`)	`false`
`PORT`	Modo HTTP: puerto para escuchar (la bandera `--port` tiene prioridad)	`3000`
`HOST`	Modo HTTP: dirección a la que vincularse (la bandera `--host` tiene prioridad)	`127.0.0.1`
`ALLOWED_HOSTS`	Modo HTTP: valores adicionales de encabezado `Host` para aceptar más allá de loopback (nombres de host separados por comas). Requerido al vincularse a una dirección LAN/pública o ejecutar detrás de un proxy inverso. Consulta Configuración del Modo HTTP.	solo loopback
`ALLOWED_ORIGINS`	Modo HTTP: lista de permitidos separada por comas de patrones de navegador `Origin`/`Referer` (se admiten comodines, p. ej. `https://*.ngrok.io`).	`http://localhost:,http://127.0.0.1:,https://localhost:,https://127.0.0.1:`
`TUNNEL_SERVER_URL`	URL del WebSocket del servidor de túnel (solo modo túnel)	`wss://tunnel.ankimcp.ai`
`MEDIA_ALLOWED_TYPES`	Tipos MIME adicionales para permitir en importaciones de rutas de archivo (separados por comas, p. ej., `application/pdf`)	-
`MEDIA_IMPORT_DIR`	Restringir importaciones de rutas de archivo a este directorio	-
`MEDIA_ALLOWED_HOSTS`	Permitir hosts específicos de red privada para importaciones de URL (separados por comas, p. ej., `192.168.1.50,my-nas`)	-

Ejemplos de Uso

Buscar y Actualizar Notas

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

Ejemplos de Sintaxis de Consulta de Anki

La herramienta findNotes soporta la poderosa sintaxis de consulta de Anki:

"deck:DeckName" - Todas las notas en un mazo específico
"tag:important" - Notas con la etiqueta "importante"
"is:due" - Tarjetas que están pendientes de repaso
"is:new" - Tarjetas nuevas que no han sido estudiadas
"added:7" - Notas añadidas en los últimos 7 días
"front:hello" - Notas con "hola" en el campo frontal
"flag:1" - Notas con bandera roja
"prop:due<=2" - Tarjetas pendientes dentro de 2 días
"deck:Spanish tag:verb" - Notas del mazo de español con etiqueta de verbo (Y)
"deck:Spanish OR deck:French" - Notas de cualquiera de los dos mazos

Notas Importantes

Manejo de CSS y HTML

La herramienta notesInfo devuelve el nombre del tipo de nota de cada nota; el CSS en sí proviene de modelStyling
La herramienta updateNoteFields admite contenido HTML en los campos y conserva el estilo CSS
Cada modelo de nota tiene su propio estilo CSS: use modelStyling para obtener el CSS específico del modelo

Advertencia de Actualización

⚠️ IMPORTANTE: Al usar updateNoteFields, NO vea la nota en el navegador de Anki mientras actualiza, o los campos no se actualizarán correctamente. Cierre el navegador o cambie a una nota diferente antes de actualizar. Consulte Problemas conocidos para más detalles.

Seguridad de Eliminación

La herramienta deleteNotes requiere confirmación explícita (confirmDeletion: true) para prevenir eliminaciones accidentales. Eliminar una nota elimina TODAS las tarjetas asociadas de forma permanente.

Seguridad

Validación de Rutas de Archivos Multimedia y URLs

Las herramientas multimedia (storeMediaFile, retrieveMediaFile, deleteMediaFile) y los campos de audio/imagen de updateNoteFields incluyen validación de seguridad para prevenir el mal uso mediante inyección de prompts:

Importaciones de rutas de archivos están restringidas solo a tipos de archivos multimedia (imágenes, audio, video). Los archivos que no son multimedia (por ejemplo, claves SSH, credenciales, configuraciones de shell) se rechazan según el tipo MIME. Configure MEDIA_ALLOWED_TYPES para permitir tipos de archivos adicionales, o MEDIA_IMPORT_DIR para restringir importaciones a un directorio específico.
Importaciones de URLs se validan contra ataques SSRF. Las solicitudes a redes privadas (10.x, 172.16.x, 192.168.x), loopback (127.x), link-local (169.254.x) y esquemas que no son HTTP(S) se bloquean. Configure MEDIA_ALLOWED_HOSTS para permitir hosts específicos de redes privadas.
Nombres de archivos se sanean para prevenir el path traversal (por ejemplo, las secuencias ../../ se eliminan).

Estas protecciones se aplican a storeMediaFile, retrieveMediaFile, deleteMediaFile y los campos de audio/imagen de updateNoteFields.

Vulnerabilidad de path traversal reportada por Hideaki Takahashi.

Protección contra DNS-Rebinding (transporte HTTP)

Cuando se ejecuta en modo HTTP, el servidor valida el encabezado Host en cada solicitud. Por defecto, solo se aceptan hosts de loopback (localhost, 127.0.0.1, ::1), independientemente del puerto. Host es un encabezado prohibido en navegadores, por lo que una página web maliciosa no puede falsificarlo; esto cierra la ruta de DNS-rebinding donde una página rebotada llega al servidor local con un Host falsificado y sin Origin, y llega a las herramientas MCP. Un Host no permitido se rechaza con 403.

Si se vincula a 0.0.0.0, se ejecuta detrás de un proxy inverso, o se expone un dominio de túnel público, configure ALLOWED_HOSTS (nombres de host separados por comas) para permitir esos hosts. Al usar túneles con ngrok, el servidor usa --host-header=rewrite, por lo que el upstream aún ve un Host de loopback. Consulte Configuración del Modo HTTP para la lista completa de opciones.

Vulnerabilidad de DNS-rebinding reportada por avishaigo-commits y yotampe-pluto.

Política de Privacidad

Este servidor MCP se ejecuta localmente en su máquina y no recopila telemetría, análisis ni datos de uso.

Política completa: https://ankimcp.ai/privacy/

Recopilación de datos: El servidor no recopila nada. Actúa como proxy de solicitudes entre su asistente de IA y su plugin local AnkiConnect.
Uso / almacenamiento: Sin almacenamiento en el servidor. Todos los datos de tarjetas permanecen en su instalación de Anki en su propio dispositivo.
Compartición con terceros: Ninguna. El servidor solo se comunica con la URL de AnkiConnect que configure (por defecto: localhost). Si habilita la sincronización integrada de AnkiWeb de Anki, eso ocurre entre su instalación de Anki y AnkiWeb directamente, fuera del alcance de este servidor.
Retención: No aplica: no se retienen datos en el servidor.
Contacto: support@ankimcp.ai

Problemas Conocidos

Para una lista completa de problemas conocidos y limitaciones, visite nuestra documentación:

Documentación de Problemas Conocidos

Limitaciones Críticas

Las Actualizaciones de Notas Fallan Cuando se Ven en el Navegador

⚠️ IMPORTANTE: Al actualizar notas con updateNoteFields, la actualización fallará silenciosamente si la nota se está viendo actualmente en la ventana del navegador de Anki. Esta es una limitación de AnkiConnect.

Solución alternativa: Cierre siempre el navegador o navegue a una nota diferente antes de actualizar.

Para más detalles y otros problemas conocidos, consulte la documentación completa.

Solución de Problemas

Error ERR_REQUIRE_ESM

Si ve un error como:

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

Esto significa que su versión de Node.js no es compatible. El servidor requiere Node.js 22.12.0+.

Nota: El runtime mínimo compatible es Node.js 22.12.0. Node.js 20 (Iron) llegó al final de su vida útil el 2026-04-30 y ya no es compatible.

Verifique su versión:

node --version

Solución: Actualice Node.js a la versión 22.12.0+. Puede descargarlo desde nodejs.org o usar un gestor de versiones como nvm.

Desarrollo

Modos de Transporte

Este servidor admite tres modos de transporte MCP mediante puntos de entrada separados:

Modo STDIO (Predeterminado)

Para clientes MCP locales como Claude Desktop
Usa entrada/salida estándar para la comunicación
Punto de entrada: dist/main-stdio.js
Ejecutar: npm run start:prod:stdio o node dist/main-stdio.js
Paquete MCPB: Usa el modo STDIO

Modo HTTP (HTTP Streamable)

Para clientes MCP remotos e integraciones basadas en web
Usa el protocolo MCP Streamable HTTP
Punto de entrada: dist/main-http.js
Ejecutar: npm run start:prod:http o node dist/main-http.js
Puerto predeterminado: 3000 (configurable mediante la variable de entorno PORT)
Host predeterminado: 127.0.0.1 (configurable mediante la variable de entorno HOST)
Endpoint MCP: http://127.0.0.1:3000/ (ruta raíz)

Modo Túnel (Túnel WebSocket Gestionado)

Para asistentes de IA basados en web mediante el servicio de túnel gestionado AnkiMCP, con autenticación integrada
El servidor MCP se ejecuta en proceso detrás de un transporte en memoria; TunnelTransport posee el servidor MCP y TunnelClient lo conecta al servicio de túnel a través de un WebSocket
Protocolo: sirve solo la revisión MCP 2025 (STDIO y HTTP también sirven 2026-07-28)
Punto de entrada: dist/main-tunnel.js
Ejecutar: node dist/main-tunnel.js --tunnel (o ankimcp --tunnel)
Autenticación: ankimcp --login / ankimcp --logout; credenciales almacenadas en ~/.ankimcp/credentials.json (0600)
Desarrollo: npm run start:dev:tunnel (modo de observación, ejecuta --tunnel --debug)

Compilación

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

main-stdio.js, main-http.js y main-tunnel.js se compilan todos en el mismo directorio dist/. Elija cuál ejecutar según sus necesidades.

Configuración del Modo HTTP

Variables de Entorno:

PORT - Puerto del servidor HTTP (predeterminado: 3000)
HOST - Dirección de enlace (predeterminado: 127.0.0.1 solo para localhost)
ALLOWED_HOSTS - Valores adicionales del encabezado Host separados por comas para aceptar más allá del conjunto de loopback integrado (localhost, 127.0.0.1, ::1). Solo nombre de host e independiente del puerto. Predeterminado: solo loopback.
ALLOWED_ORIGINS - Lista de permitidos separada por comas de patrones de Origin/Referer del navegador; se admiten comodines (por ejemplo, https://*.ngrok.io). Predeterminado: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
LOG_LEVEL - Nivel de registro (predeterminado: info)

Seguridad:

Validación del encabezado Host (protección contra DNS-rebinding) — cada solicitud HTTP debe llevar un encabezado Host que coincida con la lista de permitidos. Por defecto, solo se aceptan hosts de loopback (localhost, 127.0.0.1, ::1), independientemente del puerto. Host es un encabezado prohibido en navegadores, por lo que una página web maliciosa no puede falsificarlo; esto cierra la ruta de DNS-rebinding donde una página rebotada llega al servidor con un Host falsificado y sin Origin. Un Host no permitido se rechaza con 403.
Validación del encabezado Origin — las solicitudes del navegador con un Origin/Referer presente pero no permitido se rechazan. Las solicitudes sin Origin (curl, Postman, clientes MCP-over-HTTP) se permiten; la validación de Host es la defensa contra el rebinding.
Se vincula a localhost (127.0.0.1) por defecto.
Sin autenticación en la versión actual (soporte OAuth planificado).

Exponer el modo HTTP más allá de localhost — si se vincula a una dirección LAN/pública o coloca el servidor detrás de un proxy inverso o dominio público, debe configurar ALLOWED_HOSTS con los nombres de host que usarán los clientes; de lo contrario, cada solicitud que no sea de loopback se rechaza con 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

Cuando se vincula a 0.0.0.0/:: sin ALLOWED_HOSTS, el servidor registra una advertencia de inicio de que solo se aceptarán encabezados Host de loopback.

Docker / proxy inverso / dominio público: se aplica la misma regla. En Docker, las solicitudes generalmente llegan con el nombre de host publicado del contenedor o el Host del proxy, así que configure ALLOWED_HOSTS en consecuencia. Un proxy inverso (nginx, Caddy, Traefik) debe reenviar el Host original y tener ese nombre de host listado en ALLOWED_HOSTS, o reescribir el Host upstream a localhost. La integración integrada de --ngrok maneja esto automáticamente (ver más abajo).

Ejemplo: Modos de Ejecución

# 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

Creación de un Paquete MCPB

Para crear un paquete MCPB distribuible:

npm run mcpb:bundle

Este comando:

Sincroniza la versión de package.json a manifest.json
Elimina archivos antiguos de .mcpb
Compila el proyecto TypeScript
Empaqueta dist/ y node_modules/ en un archivo .mcpb
Ejecuta mcpb clean para eliminar devDependencies (optimiza el paquete de ~47MB a ~10MB)

El archivo de salida se llamará anki-mcp-server-X.X.X.mcpb y se puede distribuir para instalación con un clic.

Qué se Incluye en el Paquete

El paquete MCPB incluye:

JavaScript compilado (directorio dist/ - incluye los tres puntos de entrada)
Solo dependencias de producción (node_modules/ - devDependencies eliminadas por mcpb clean)
Metadatos del paquete (package.json)
Configuración del manifiesto (manifest.json - configurado para usar main-stdio.js)
Icono (icon.png)

Los archivos fuente, pruebas y configuraciones de desarrollo se excluyen automáticamente mediante .mcpbignore.

Registro en Claude Desktop

Cuando se ejecuta como extensión MCPB en Claude Desktop, los registros se escriben en:

Ubicación del Registro: ~/Library/Logs/Claude/ (macOS)

Los registros se dividen en varios archivos:

main.log - Registros generales de la aplicación Claude Desktop
mcp-server-Anki MCP Server.log - Mensajes del protocolo MCP para esta extensión
mcp.log - Registros MCP combinados de todos los servidores

Nota: La salida del registrador pino (mensajes INFO, ERROR, WARN del código del servidor) va a stderr y aparece en los archivos de registro específicos de MCP. Claude Desktop determina qué archivo de registro recibe qué mensajes, pero generalmente:

Inicio de la aplicación y comunicación del protocolo MCP → registro específico de MCP
Registro interno del servidor (pino) → tanto el registro específico de MCP como a veces main.log

Para ver los registros en tiempo real:

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

Depuración del Servidor MCP

Puede depurar el servidor MCP usando el MCP Inspector y adjuntando un depurador desde su IDE (WebStorm, VS Code, etc.).

Nota para el Modo HTTP: Al probar el modo HTTP (Streamable HTTP) con MCP Inspector, use "Connection Type: Via Proxy" para evitar errores CORS.

Paso 1: Configurar el Servidor de Depuración en MCP Inspector

El mcp-inspector-config.json ya incluye una configuración de servidor de depuración:

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

Paso 2: Iniciar el servidor de depuración

Ejecuta el MCP Inspector con el servidor de depuración:

npm run inspector:debug

Esto iniciará el servidor con la depuración de Node.js habilitada en el puerto 9229 y pausará la ejecución en la primera línea.

Paso 3: Adjuntar el depurador desde tu IDE

WebStorm

Ve a Run → Edit Configurations
Añade una nueva configuración Attach to Node.js/Chrome
Establece el puerto en 9229
Haz clic en Debug para adjuntar

VS Code

Abre el panel de depuración (Ctrl+Shift+D / Cmd+Shift+D)
Selecciona la configuración Debug MCP Server (Attach)
Pulsa F5 para adjuntar

Paso 4: Establecer puntos de interrupción y depurar

Una vez adjuntado, puedes:

Establecer puntos de interrupción en tus archivos fuente de TypeScript
Avanzar paso a paso por la ejecución del código
Inspeccionar variables y la pila de llamadas
Usar la consola de depuración para evaluar expresiones

El depurador funcionará con mapas de origen, lo que te permite depurar el código TypeScript original en lugar del JavaScript compilado.

Depuración con Claude Desktop

También puedes depurar el servidor MCP mientras se ejecuta dentro de Claude Desktop habilitando el depurador de Node.js y adjuntando tu IDE.

Paso 1: Configurar Claude Desktop para la depuración

Actualiza tu configuración de Claude Desktop para habilitar la depuración:

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

Cambio clave: Añade --inspect=9229 antes de la ruta a dist/main-stdio.js

Opciones de depuración:

--inspect=9229 - Inicia el depurador inmediatamente, no bloquea (recomendado)
--inspect-brk=9229 - Pausa la ejecución hasta que el depurador se adjunte (para depurar problemas de inicio)

Paso 2: Reiniciar Claude Desktop

Después de guardar la configuración, reinicia Claude Desktop. El servidor MCP ahora se ejecutará con la depuración habilitada en el puerto 9229.

Paso 3: Adjuntar el depurador desde tu IDE

WebStorm

Ve a Run → Edit Configurations
Haz clic en el botón + y selecciona Attach to Node.js/Chrome
Configura:
- Name: Attach to Anki MCP (Claude Desktop)
- Host: localhost
- Port: 9229
- Attach to: Node.js < 8 o Chrome or Node.js > 6.3 (dependiendo de la versión de WebStorm)
Haz clic en OK
Haz clic en Debug (Shift+F9) para adjuntar

VS Code

Añade a .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"]
    }
  ]
}

Abre el panel de depuración (Ctrl+Shift+D / Cmd+Shift+D)
Selecciona Attach to Anki MCP (Claude Desktop)
Pulsa F5 para adjuntar

Paso 4: Depurar en tiempo real

Una vez adjuntado, puedes:

Establecer puntos de interrupción en tus archivos fuente de TypeScript (por ejemplo, src/mcp/primitives/essential/tools/create-model.tool.ts)
Usar Claude Desktop normalmente: los puntos de interrupción se activarán cuando se invoquen las herramientas
Avanzar paso a paso por la ejecución del código
Inspeccionar variables y la pila de llamadas
Usar la consola de depuración

Ejemplo: Establece un punto de interrupción en create-model.tool.ts en la línea 119, luego pide a Claude que cree un nuevo modelo. ¡El depurador se pausará en tu punto de interrupción!

Nota: El depurador permanece adjunto mientras Claude Desktop esté en ejecución. Puedes desconectar/reconectar en cualquier momento sin reiniciar Claude Desktop.

Comandos de compilación

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

Pruebas del paquete npm (local)

Prueba el paquete npm localmente antes de publicarlo:

# 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

Cómo funciona:

npm pack crea un archivo .tgz idéntico al que crearía npm publish
Instalar desde .tgz simula lo que los usuarios obtienen de npm install -g ankimcp
Esto te permite probar la experiencia completa del usuario antes de publicar en npm

Comandos de prueba

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)

Cobertura de pruebas

El proyecto mantiene umbrales mínimos de cobertura del 70% para:

Ramas
Funciones
Líneas
Sentencias

Los informes de cobertura se generan en el directorio coverage/.

Versionado

Este proyecto sigue Versionado Semántico con un enfoque de desarrollo previo a la versión 1.0:

0.x.x - Versiones Beta/Desarrollo (fase actual)
- 0.1.x - Correcciones de errores y parches
- 0.2.0+ - Nuevas funciones o mejoras menores
- Los cambios disruptivos son aceptables en versiones 0.x
1.0.0 - Primera versión estable
- Se publicará cuando la API sea estable y esté probada
- Los cambios disruptivos requerirán incrementos de versión mayor (2.0.0, etc.)

Estado actual: 0.27.0 - Desarrollo beta activo. Las funciones recientes incluyen análisis de revisión en toda la colección (review_stats ahora agrega datos en todos los mazos cuando se omite deck), gestión de campos de modelo (addModelField, removeModelField, renameModelField, repositionModelField), creación de notas por lotes (addNotes), túnel ngrok integrado (bandera --ngrok), gestión de archivos multimedia, gestión de modelos/plantillas y estadísticas completas de mazos. Las API pueden cambiar según los comentarios y las pruebas.

Evolución de la especificación MCPB

Este proyecto apunta a la especificación de paquetes MCPB de Anthropic, que aún está en evolución. Seguimos la especificación en https://github.com/modelcontextprotocol/mcpb y podemos introducir cambios disruptivos para mantener el cumplimiento. Los cambios disruptivos están permitidos bajo el esquema de versionado 0.x.x.

Proyectos similares

Si estás explorando integraciones de Anki MCP, aquí hay otros proyectos en este espacio:

scorzeth/anki-mcp-server

Estado: Parece estar abandonado (sin actualizaciones recientes)
Implementación temprana de la integración de Anki MCP

nailuoGG/anki-mcp-server

Enfoque: Implementación ligera de un solo archivo
Arquitectura: Estructura de código procedural con todas las herramientas en un solo archivo
Adecuado para: Casos de uso simples, dependencias mínimas

Por qué este proyecto es diferente:

Arquitectura de nivel empresarial: Construido sobre NestJS con inyección de dependencias
Diseño modular: Cada herramienta es una clase separada con una clara separación de responsabilidades
Mantenibilidad: Fácil de extender con nuevas funciones sin tocar el código existente
Pruebas: Suite de pruebas integral con requisito de cobertura del 70%
Seguridad de tipos: TypeScript estricto con validación Zod
Manejo de errores: Manejo robusto de errores con comentarios útiles para el usuario
Listo para producción: Registro adecuado, informes de progreso y soporte de paquetes MCPB
Escalabilidad: Puede crecer fácilmente desde herramientas básicas hasta flujos de trabajo complejos

Caso de uso: Si necesitas una base sólida para construir integraciones avanzadas de Anki o planeas extender la funcionalidad significativamente, el enfoque arquitectónico de este proyecto facilita el mantenimiento y la escalabilidad a lo largo del tiempo.

Enlaces útiles

Licencia y atribuciones

Este proyecto está licenciado bajo la Licencia MIT — consulta LICENSE para el texto completo.

Atribuciones de terceros

Anki® es una marca registrada de Ankitects Pty Ltd. Este proyecto es una herramienta no oficial de terceros y no está afiliado, respaldado ni patrocinado por Ankitects Pty Ltd. El logotipo de Anki se utiliza bajo la licencia alternativa para referenciar Anki con un enlace a https://apps.ankiweb.net. Para la aplicación oficial de Anki, visita https://apps.ankiweb.net.
Protocolo de Contexto de Modelo (MCP) es un estándar abierto de Anthropic. El logotipo de MCP proviene del repositorio oficial de documentación de MCP y se utiliza bajo la Licencia MIT. Para obtener más información sobre MCP, visita https://modelcontextprotocol.io.
Este es un proyecto independiente que une las tecnologías de Anki y MCP. Todas las marcas comerciales, marcas de servicio, nombres comerciales, nombres de productos y logotipos son propiedad de sus respectivos dueños.