Anki MCP

Servidor MCP de Anki

Beta - Este proyecto está en desarrollo activo. Las APIs y funcionalidades pueden cambiar.

Un servidor del Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con Anki, la aplicación de tarjetas de memoria con 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 funcionalidades 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, incluyendo la guía de configuración del revisor y el mazo de Anki de muestra.

Casos de Uso de Ejemplo

Tres prompts representativos que muestran los flujos de herramientas que este servidor habilita:

1. "Ayúdame a repasar mi mazo de español." — El asistente se sincroniza 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.

2. "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).

3. "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 en el navegador (guiSelectedNotes + notesInfo), y actualiza el campo frontal con una etiqueta <img> (updateNoteFields).

Herramientas Disponibles

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

Herramientas Esenciales

Repaso y Estudio

• sync - Sincronizar con AnkiWeb para obtener los últimos datos y enviar cambios
• get_due_cards - Obtener tarjetas pendientes de repaso, opcionalmente filtradas por mazo
• get_cards - Obtener tarjetas con filtrado flexible por estado (pendientes, nuevas, en aprendizaje, suspendidas, enterradas) y mazo
• present_card - Mostrar una tarjeta para repaso con su lado de pregunta/frente
• rate_card - Calificar el rendimiento de la tarjeta (Otra vez, Difícil, Bien, Fácil) y programar el próximo repaso

Nota: El contenido de front/back de la tarjeta se renderiza por tarjeta desde su propia plantilla (como lo muestra Anki), por lo que las tarjetas invertidas y de tipo cloze 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 - Listar todos los mazos, opcionalmente con estadísticas de conteo de tarjetas por mazo
• deckStats - Obtener estadísticas completas para un solo mazo (conteos, distribuciones de facilidad/intervalo)
• createDeck - Crear un nuevo mazo vacío (soporta Parent::Child, máximo 2 niveles)
• changeDeck - Mover tarjetas a un mazo diferente (se crea si no existe)

Gestión de Notas

• addNote - Crear una sola nota con campos y etiquetas especificados
• addNotes - Crear en lote hasta 100 notas que comparten mazo y modelo (se admite éxito parcial)
• findNotes - Buscar notas usando la sintaxis de consulta de Anki (deck:, tag:, is:due, etc.)
• notesInfo - Obtener información detallada sobre notas (campos, etiquetas, estilos CSS)
• updateNoteFields - Actualizar campos de notas existentes (consciente de CSS, admite contenido HTML)
• deleteNotes - Eliminar notas y todas las tarjetas asociadas (destructivo, requiere confirmación)

Gestión de Etiquetas

• getTags - Obtener todas las etiquetas de la colección (usar primero para evitar duplicados)
• addTags - Añadir etiquetas separadas por espacios a notas especificadas
• removeTags - Eliminar etiquetas separadas por espacios de notas especificadas
• replaceTags - Renombrar una etiqueta en las notas especificadas
• clearUnusedTags - Eliminar etiquetas huérfanas no utilizadas por ninguna nota (destructivo)

Gestión de Medios

• getMediaFilesNames - Listar archivos multimedia en collection.media, opcionalmente filtrados por patrón
• retrieveMediaFile - Descargar un archivo multimedia como contenido base64
• storeMediaFile - Subir medios desde datos base64, una ruta de archivo absoluta o una URL
• deleteMediaFile - Eliminar un archivo multimedia de collection.media (destructivo)

💡 Mejor Práctica para Imágenes:

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

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

Gestión de Modelos/Plantillas

• modelNames - Listar todos los tipos de nota/modelos disponibles
• modelFieldNames - Obtener nombres de campo para un tipo de nota específico
• modelStyling - Obtener información de estilos CSS para un tipo de nota
• modelTemplates - Obtener las plantillas de tarjeta (HTML Frontal y Posterior) para un tipo de nota
• createModel - Crear un nuevo tipo de nota con campos personalizados, plantillas de tarjeta y CSS (ej., modelos RTL)
• updateModelStyling - Actualizar los estilos CSS para un tipo de nota existente (se aplica a todas sus tarjetas)
• updateModelTemplates - Actualizar las plantillas de tarjeta (HTML Frontal y Posterior) para un tipo de nota existente (se aplica a todas sus tarjetas)
• addModelField - Añadir un nuevo campo a un tipo de nota existente (añadido al final o insertado en una posición específica)
• removeModelField - Eliminar un campo de un tipo de nota existente (elimina su contenido de todas las notas; requiere confirmación explícita)
• renameModelField - Renombrar un campo en un tipo de nota existente (las plantillas de tarjeta que referencian el nombre antiguo deben actualizarse por separado)
• repositionModelField - Cambiar 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
• review_stats - Análisis del historial de repasos (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 trabajo de edición/creación de notas y gestión de mazos, no para sesiones de repaso.

• guiBrowse - Abrir el Navegador de Tarjetas y buscar tarjetas
• guiSelectCard - Seleccionar una tarjeta específica en el Navegador de Tarjetas
• guiSelectedNotes - Obtener IDs de notas actualmente seleccionadas en el Navegador de Tarjetas
• guiAddCards - Abrir el diálogo Añadir Tarjetas con detalles de nota preestablecidos
• guiEditNote - Abrir el editor de notas para una nota específica
• guiDeckOverview - Abrir el diálogo de Vista General del Mazo para un mazo específico
• guiDeckBrowser - Abrir el diálogo del Navegador de Mazos
• guiCurrentCard - Obtener información sobre la tarjeta actual en modo repaso
• guiShowQuestion - Mostrar el lado de la pregunta de la tarjeta actual
• guiShowAnswer - Mostrar el lado de la respuesta de la tarjeta actual
• guiUndo - Deshacer la última acción en Anki

Requisitos Previos

• Anki con el plugin AnkiConnect instalado
• Node.js 22.12.0+

Instalación

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

npm (global o npx)

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

Instálalo globalmente para clientes que ejecuten 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:

1. Descarga el último paquete .mcpb de la página de Lanzamientos
2. 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
3. Configura la URL de AnkiConnect si es necesario (por defecto http://localhost:8765)
4. 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 tutorial de integración desde cero con un mazo de muestra pre-poblado se encuentra en docs/reviewer-setup.md.

Instalar desde el Código Fuente (para desarrollo)

Para desarrollo o uso avanzado:

npm install
npm run build

Conectar 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 locales basadas en web.
• Remoto — una IA alojada/remota (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 más ligera no autenticada, ngrok.

Local

El servidor se ejecuta en el mismo ordenador 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, 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 potenciado por IA
• Cline - Extensión de VS Code para asistencia de IA
• Zed Editor - Editor de código rápido y moderno
• 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 necesita 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"
      }
    }
  }
}

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

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 construido.

HTTP (IA local basada en web)

El modo HTTP ejecuta el servidor como un servidor web local que habla el protocolo HTTP Transmisible MCP. 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 Remotas exponen al mundo exterior. Por sí solo, el modo HTTP se enlaza solo a localhost.

¿Enlazando 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 cabeceras de loopback Host por defecto para protección contra reenlace DNS — establece ALLOWED_HOSTS al nombre(s) 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 necesita 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 que un servidor HTTP local sea accesible 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 sin protección, 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 los 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 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 un proceso de túnel separado, e inicias sesión una sola vez.

Iniciar sesión (flujo de dispositivo OAuth):

El modo túnel utiliza la Concesión de Autorización de Dispositivo OAuth 2.0. Iniciar sesión abre tu navegador automáticamente en una página de aprobación con el código ya incrustado en la URL — no hay que escribir nada, solo aprobar. (Si el navegador no puede abrirse, la terminal imprime una URL de verificación y un código para ingresar manualmente como alternativa). 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, y luego continúa con el túnel. Este inicio de sesión automático requiere una terminal interactiva — cuando stdout no es una TTY (systemd, Docker headless, CI), el servidor falla rápidamente y te pide que ejecutes 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	Valor por defecto
TUNNEL_SERVER_URL	URL del WebSocket del servidor túnel (el valor del flag --tunnel/--login sobrescribe 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/autenticación 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 (McpModule se inicia sin transporte integrado). TunnelMcpService conecta ese transporte en memoria al servidor MCP, y TunnelClient lo une al servicio de túnel remoto a través de un WebSocket — retransmitiendo las solicitudes MCP de entrada y las respuestas de salida. AnkiConnect solo es contactado en tu máquina local.

ngrok (alternativa no autenticada)

Si prefieres exponer el modo HTTP local públicamente sin una cuenta en el túnel gestionado, el flag integrado --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 no está autenticada — cualquiera con la URL puede acceder a tu Anki, por lo que es menos segura que el Túnel. Prefiere el Túnel a menos que tengas una razón específica para gestionar tu propio endpoint ngrok. (Requiere una instalación global de ngrok y un authtoken).

El flag --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 (ver protección contra DNS-rebinding) sin que tengas que añadir el dominio público *.ngrok a ALLOWED_HOSTS. Si en su lugar ejecutas ngrok manualmente, usa el mismo flag — 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 <port>              Port to listen on (HTTP mode, default: 3000)
  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks all write operations)
  --help                         Show help message

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

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

Modo de Solo Lectura (todos los modos)

El flag --read-only previene cualquier modificación en tu colección de Anki. Cuando está habilitado:

• Todas las operaciones de lectura funcionan normalmente (explorar mazos, ver tarjetas, buscar notas)
• Las operaciones de revisión están permitidas (sincronizar, responderTarjetas, suspender/activar)
• Las modificaciones de contenido están bloqueadas (añadirNota, eliminarNotas, crearMazo, actualizarCamposNota, etc.)
• Útil para explorar de forma segura los datos de Anki sin riesgo de cambios accidentales

# 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 mediante 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 Configuración
• O editando manualmente el archivo de configuración

Configuración

Añade 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 la ruta real de tu proyecto.

Ubicaciones del Archivo 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	Valor por defecto
ANKI_CONNECT_URL	URL de AnkiConnect	http://localhost:8765
ANKI_CONNECT_API_VERSION	Versión de la API	6
ANKI_CONNECT_API_KEY	Clave 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
ALLOWED_HOSTS	Modo HTTP: valores de cabecera Host adicionales para aceptar más allá de loopback (nombres de host separados por comas). Requerido al vincular a una dirección LAN/pública o ejecutar detrás de un proxy inverso. Ver Configuración del Modo HTTP.	solo loopback
ALLOWED_ORIGINS	Modo HTTP: lista de permitidos separada por comas de patrones Origin/Referer del navegador (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 túnel (solo modo túnel)	wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPES	Tipos MIME adicionales a permitir para importaciones de ruta de archivo (separados por comas, p. ej., application/pdf)	-
MEDIA_IMPORT_DIR	Restringir importaciones de ruta de archivo a este directorio	-
MEDIA_ALLOWED_HOSTS	Permitir hosts de red privada específicos 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 potente 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 revisión
• "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 en los próximos 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 mazos

Notas Importantes

Manejo de CSS y HTML

• La herramienta notesInfo devuelve información de estilo CSS para una correcta conciencia de renderizado
• La herramienta updateNoteFields soporta contenido HTML en los campos y preserva el estilo CSS
• Cada modelo de nota tiene su propio estilo CSS - usa modelStyling para obtener el CSS específico del modelo

Advertencia de Actualización

⚠️ IMPORTANTE: Al usar updateNoteFields, NO veas la nota en el navegador de Anki mientras se actualiza, o los campos no se actualizarán correctamente. Cierra el navegador o cambia a una nota diferente antes de actualizar. Consulta Problemas Conocidos para más detalles.

Seguridad en la Eliminación

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

Seguridad

Validación de Ruta de Archivo Multimedia y URL

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

• Las importaciones de ruta de archivo están restringidas solo a tipos de archivos multimedia (imágenes, audio, video). Los archivos no multimedia (p. ej., claves SSH, credenciales, configuraciones de shell) son rechazados según el tipo MIME. Configura MEDIA_ALLOWED_TYPES para permitir tipos de archivo adicionales, o MEDIA_IMPORT_DIR para restringir las importaciones a un directorio específico.
• Las importaciones de URL 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 no HTTP(S) están bloqueadas. Configura MEDIA_ALLOWED_HOSTS para permitir hosts de red privada específicos.
• Los nombres de archivo se sanean para prevenir el path traversal (p. ej., las secuencias ../../ se eliminan).

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

Vulnerabilidad de path traversal reportada por Hideaki Takahashi.

Protección contra DNS-Rebinding (transporte HTTP)

Al ejecutarse en modo HTTP, el servidor valida la cabecera Host en cada solicitud. Por defecto, solo se aceptan hosts de loopback (localhost, 127.0.0.1, ::1), independientemente del puerto. Host es una cabecera prohibida por el navegador, por lo que una página web maliciosa no puede falsificarla — esto cierra la vía de DNS-rebinding donde una página redirigida alcanza el servidor local con un Host suplantado y sin Origin, y alcanza las herramientas MCP. Un Host no permitido es rechazado con 403.

Si te vinculas a 0.0.0.0, ejecutas detrás de un proxy inverso o expones un dominio de túnel público, establece ALLOWED_HOSTS (nombres de host separados por comas) para permitir esos hosts. Al hacer túnel con ngrok, el servidor usa --host-header=rewrite, por lo que el ascendente aún ve un Host de loopback. Consulta 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 tu 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. Hace de proxy entre tu asistente de IA y tu plugin local AnkiConnect.
• Uso / almacenamiento: Sin almacenamiento en el lado del servidor. Todos los datos de las tarjetas permanecen en tu instalación de Anki en tu propio dispositivo.
• Compartición con terceros: Ninguna. El servidor solo habla con la URL de AnkiConnect que configures (por defecto: localhost). Si habilitas la sincronización integrada de AnkiWeb de Anki, eso ocurre entre tu instalación de Anki y AnkiWeb directamente — fuera del alcance de este servidor.
• Retención: No aplica — no se retienen datos en el lado del servidor.
• Contacto: support@ankimcp.ai

Problemas Conocidos

Para una lista completa de problemas conocidos y limitaciones, por favor visita 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 usando 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: Siempre cierra el navegador o navega a una nota diferente antes de actualizar.

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

Solución de Problemas

Error ERR_REQUIRE_ESM

Si ves un error como:

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

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

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

Verifica tu versión:

node --version

Solución: Actualiza Node.js a la versión 22.12.0 o superior. Puedes descargarlo desde nodejs.org o usar un gestor de versiones como nvm.

Desarrollo

Modos de Transporte

Este servidor soporta tres modos de transporte MCP a través de puntos de entrada separados:

Modo STDIO (Predeterminado)

• Para clientes MCP locales como Claude Desktop
• Utiliza 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: Utiliza el modo STDIO

Modo HTTP (HTTP Transmisible)

• Para clientes MCP remotos e integraciones basadas en web
• Utiliza el protocolo HTTP Transmisible MCP
• 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 a través del servicio de túnel gestionado AnkiMCP, con autenticación integrada
• El servidor MCP se ejecuta en proceso detrás de un transporte en memoria; TunnelMcpService lo conecta al servidor MCP y TunnelClient lo une al servicio de túnel a través de un WebSocket
• 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 observador, ejecuta --tunnel --debug)

Construcción

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

main-stdio.js, main-http.js y main-tunnel.js se construyen todos en el mismo directorio dist/. Elige cuál ejecutar según tus 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 de cabecera Host separados por comas para aceptar más allá del conjunto de bucle invertido incorporado (localhost, 127.0.0.1, ::1). Solo nombre de host y agnóstico al puerto. Predeterminado: solo bucle invertido.
• ALLOWED_ORIGINS - Lista de permitidos separada por comas de patrones Origin/Referer del navegador; se admiten comodines (p. ej., 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 de cabecera Host (protección contra reenlace DNS) — cada solicitud HTTP debe llevar una cabecera Host que coincida con la lista de permitidos. De forma predeterminada, solo se aceptan hosts de bucle invertido (localhost, 127.0.0.1, ::1), independientemente del puerto. Host es una cabecera prohibida por el navegador, por lo que una página web maliciosa no puede falsificarla — esto cierra la vía de reenlace DNS donde una página reenlazada llega al servidor con un Host suplantado y sin Origin. Un Host no permitido se rechaza con 403.
• Validación de cabecera Origin — las solicitudes del navegador con un Origin/Referer presente pero no permitido son rechazadas. Las solicitudes sin Origin (curl, Postman, clientes MCP sobre HTTP) están permitidas; la validación de Host es la defensa contra el reenlace.
• Se enlaza a localhost (127.0.0.1) de forma predeterminada.
• Sin autenticación en la versión actual (soporte OAuth planificado).

Exponer el modo HTTP más allá de localhost — si te enlazas a una dirección LAN/pública o pones el servidor detrás de un proxy inverso o dominio público, debes establecer ALLOWED_HOSTS en el/los nombre(s) de host que usarán los clientes, de lo contrario, cada solicitud que no sea de bucle invertido 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 te enlazas a 0.0.0.0/:: sin ALLOWED_HOSTS, el servidor registra una advertencia de inicio de que solo se aceptarán cabeceras Host de bucle invertido.

Docker / proxy inverso / dominio público: se aplica la misma regla. En Docker, las solicitudes suelen llegar con el nombre de host publicado del contenedor o el Host del proxy, así que establece 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 ascendente a localhost. La integración incorporada 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

Construir un Paquete MCPB

Para crear un paquete MCPB distribuible:

npm run mcpb:bundle

Este comando hará lo siguiente:

1. Sincronizar la versión de package.json a manifest.json
2. Eliminar archivos antiguos de .mcpb
3. Construir el proyecto TypeScript
4. Empaquetar dist/ y node_modules/ en un archivo .mcpb
5. Ejecutar 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 solo 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 a través de .mcpbignore.

Registro en Claude Desktop

Al ejecutarse como una 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

Depurar el Servidor MCP

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

Nota para el Modo HTTP: Al probar el modo HTTP (HTTP Transmisible) con el Inspector MCP, usa "Tipo de Conexión: Via Proxy" para evitar errores CORS.

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

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 Inspector MCP 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

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

VS Code

1. Abre el panel de Depuración (Ctrl+Shift+D / Cmd+Shift+D)
2. Selecciona la configuración Debug MCP Server (Attach)
3. Presiona 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 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 fuente, permitiéndote depurar el código TypeScript original en lugar del JavaScript compilado.

Depurar 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 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 - Iniciar el depurador inmediatamente, no bloquea (recomendado)
• --inspect-brk=9229 - Pausar la ejecución hasta que se adjunte el depurador (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

1. Ve a Run → Edit Configurations
2. Haz clic en el botón + y selecciona Attach to Node.js/Chrome
3. 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)
4. Haz clic en OK
5. Haz clic en Debug (Shift+F9) para adjuntar

VS Code

1. 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"]
    }
  ]
}

2. Abre el panel de Depuración (Ctrl+Shift+D / Cmd+Shift+D)
3. Selecciona Attach to Anki MCP (Claude Desktop)
4. Presiona F5 para adjuntar

Paso 4: Depurar en Tiempo Real

Una vez adjuntado, puedes:

• Establecer puntos de interrupción en tus archivos fuente TypeScript (p. ej., src/mcp/primitives/essential/tools/create-model.tool.ts)
• Usar Claude Desktop normalmente - los puntos de interrupción se alcanzará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 se esté ejecutando. Puedes desadjuntar/readjuntar en cualquier momento sin reiniciar Claude Desktop.

Comandos de Construcció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

Prueba del Paquete NPM (Local)

Prueba el paquete npm localmente antes de publicar:

# 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 de usuario completa 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 de cobertura mínimos del 70% para:

• Ramas
• Funciones
• Líneas
• Sentencias

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

Versionado

Este proyecto sigue el Versionado Semántico con un enfoque de desarrollo pre-1.0:

• 0.x.x - Versiones Beta/Desarrollo (fase actual)

  • 0.1.x - Correcciones de errores y parches
  • 0.2.0+ - Nuevas funcionalidades o mejoras menores
  • Cambios disruptivos son aceptables en versiones 0.x

• 1.0.0 - Primer lanzamiento estable

  • Se lanzará 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.22.0 - Desarrollo beta activo. Las funcionalidades recientes incluyen análisis de revisión de toda la colección (review_stats ahora agrega a través de 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 APIs pueden cambiar según los comentarios y las pruebas.

Evolución de la especificación MCPB

Este proyecto apunta a la especificación de paquete MCPB de Anthropic, que aún está evolucionando. 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 Anki MCP

nailuoGG/anki-mcp-server

• Enfoque: Implementación ligera en un solo archivo
• Arquitectura: Estructura de código procedimental con todas las herramientas en un archivo
• Ideal 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 un requisito de cobertura del 70%
• Seguridad de tipos: TypeScript estricto con validación Zod
• Manejo de errores: Manejo robusto de errores con retroalimentación útil para el usuario
• Listo para producción: Registro adecuado, informes de progreso y soporte para 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 con 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

• Documentación del Model Context Protocol
• Documentación de la API de AnkiConnect
• Descarga de Claude Desktop
• Construyendo Extensiones de Escritorio (Blog de Anthropic)
• Repositorio de Servidores MCP
• Documentación de NestJS
• Sitio Web Oficial de Anki

Licencia y Atribución

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

Copyright © 2026 Anatoly Tarnavsky.

Atribuciones de Terceros

• Anki® es una marca registrada de Ankitects Pty Ltd. Este proyecto es una herramienta de terceros no oficial y no está afiliado, respaldado ni patrocinado por Ankitects Pty Ltd. El logotipo de Anki se utiliza bajo la licencia alternativa para referenciar a Anki con un enlace a https://apps.ankiweb.net. Para la aplicación oficial de Anki, visita https://apps.ankiweb.net.

• Model Context Protocol (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 más información sobre MCP, visita https://modelcontextprotocol.io.

• Este es un proyecto independiente que conecta 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.