Anki MCP

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona una integración fluida con Anki, permitiendo que asistentes de IA interactúen con tu colección de tarjetas de estudio. Crea, lee, actualiza y gestiona tarjetas de Anki de forma programática a través de una interfaz estandarizada.

GitHub
2
Prueba este MCPPatrocinado

Documentación

Servidor Anki MCP

Un servidor del Protocolo de Contexto de Modelos (MCP) que proporciona una integración perfecta con Anki, permitiendo que los asistentes de IA interactúen con tu colección de tarjetas de memoria. Crea, lee, actualiza y gestiona tarjetas de Anki programáticamente a través de una interfaz estandarizada.

Características

  • 🎴 Gestión de Tarjetas: Crea, recupera y actualiza tarjetas de memoria con personalización completa de campos
  • 🔍 Búsqueda Inteligente: Consulta tarjetas por ID, palabras clave, etiquetas, mazos o cualquier sintaxis de búsqueda de Anki
  • 📊 Integración de Repaso: Accede a tarjetas pendientes, tarjetas nuevas y responde tarjetas programáticamente
  • 🎵 Soporte Multimedia: Manejo automático de audio e imágenes (archivos locales, URLs o medios existentes)
  • 🔄 Operaciones por Lote: Crea múltiples tarjetas de manera eficiente en una sola operación
  • 🎯 Herramientas Genéricas: Herramientas flexibles que funcionan con cualquier mazo, tipo de nota y configuración de campos

Requisitos Previos

  1. Aplicación de Escritorio Anki - Debe estar ejecutándose durante el uso del servidor MCP
  2. Complemento AnkiConnect - Instalar desde Anki: Herramientas → Complementos → Obtener Complementos → Código: 2055492159

⚠️ Importante: Anki debe estar ejecutándose con AnkiConnect habilitado para que este servidor MCP funcione.

Recursos

  • anki://search/deckcurrent - Todas las tarjetas del mazo actual
  • anki://search/isdue - Tarjetas pendientes de repaso
  • anki://search/isnew - Tarjetas nuevas no vistas
  • Consultas personalizadas: anki://search/tag:vocabulary, anki://search/deck:Spanish, etc.

Herramientas

  • update_card - Actualizar tarjetas/notas (responder, actualizar campos, actualizar etiquetas)
  • add_card - Crear una nueva tarjeta de memoria con mazo, modelo y campos personalizados
  • batch_add_card - Crear múltiples tarjetas de memoria a la vez
  • get_due_cards - Obtener lista de tarjetas pendientes de repaso
  • get_new_cards - Obtener lista de tarjetas nuevas no vistas
  • get_card - Recuperar información detallada de tarjetas por ID o consulta

Desarrollo

Instalar dependencias:

npm install

Compilar el servidor:

npm run build

Para desarrollo con reconstrucción automática:

npm run watch

Archivos Multimedia

Cómo se Manejan los Archivos Multimedia

Cuando agregas tarjetas con imágenes o archivos de audio, el servidor maneja automáticamente diferentes tipos de fuentes multimedia:

  1. Rutas de Archivos Locales: Si proporcionas una ruta absoluta a un archivo en tu computadora (por ejemplo, /Users/mycomputer/Documents/images/prune.jpg), el servidor:

    • Leerá el archivo desde tu disco
    • Lo convertirá a base64
    • Lo subirá a la colección de medios de Anki usando la API storeMediaFile
    • Lo referenciará en la tarjeta por nombre de archivo

  2. URLs: Si proporcionas una URL (por ejemplo, https://example.com/image.jpg), Anki-Connect descargará el archivo automáticamente cuando se cree la tarjeta.

  3. Medios Existentes: Si proporcionas solo un nombre de archivo (por ejemplo, prune.jpg), asume que el archivo ya existe en la carpeta de medios de Anki.

Solución de Problemas con Imágenes

Si las imágenes no se muestran correctamente en Anki:

  1. Verifica la ruta del archivo: Asegúrate de que la ruta a tu archivo de imagen sea correcta y que el archivo exista
  2. Permisos de archivo: Asegúrate de que la aplicación pueda leer el archivo
  3. Formatos compatibles: Anki admite formatos de imagen comunes (JPG, PNG, GIF, SVG, WebP)
  4. Tamaño del archivo: Los archivos muy grandes podrían causar problemas
  5. Caracteres especiales: Evita caracteres especiales en los nombres de archivo cuando sea posible

El servidor ahora manejará automáticamente las rutas de archivos locales, por lo que no necesitas copiar manualmente las imágenes a la carpeta de medios de Anki.

Instalación y Configuración

Instalación

  1. Clona o descarga este repositorio
  2. Instala las dependencias: 
    npm install
  3. Compila el servidor: 
    npm run build

Configuración con Claude Desktop

Agrega la configuración del servidor a tu archivo de configuración de Claude Desktop:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "anki-mcp-server": {
      "command": "/absolute/path/to/anki-mcp-server/build/index.js"
    }
  }
}

💡 Consejo: Reemplaza /absolute/path/to/anki-mcp-server con la ruta completa real donde clonaste este repositorio.

Configuración con Otros Clientes MCP

Este servidor sigue el protocolo MCP estándar y puede usarse con cualquier cliente compatible con MCP. Configúralo como un servidor basado en stdio apuntando a build/index.js.

Verificación

Después de la configuración:

  1. Reinicia Claude Desktop (o tu cliente MCP)
  2. Asegúrate de que Anki esté ejecutándose con AnkiConnect instalado
  3. El servidor debería aparecer en tus servidores MCP disponibles
  4. Prueba con una consulta simple como "Muéstrame 5 tarjetas pendientes de Anki"

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser desafiante. Recomendamos usar el Inspector MCP, que está disponible como script de paquete:

npm run inspector

El Inspector proporcionará una URL para acceder a las herramientas de depuración en tu navegador donde podrás:

  • Probar llamadas de herramientas interactivamente
  • Ver registros de solicitudes/respuestas
  • Depurar problemas de conexión
  • Validar esquemas de herramientas

Solución de Problemas

El servidor no aparece en Claude Desktop:

  • Verifica que la ruta en la configuración sea absoluta (no relativa)
  • Comprueba que build/index.js exista (ejecuta npm run build)
  • Reinicia Claude Desktop después de los cambios de configuración

Errores de "Conexión rechazada" o tiempo de espera:

  • Asegúrate de que Anki esté ejecutándose
  • Verifica que AnkiConnect esté instalado (Herramientas → Complementos)
  • Comprueba que la configuración de AnkiConnect permita conexiones localhost (predeterminado)

Las tarjetas no se actualizan/crean:

  • Cierra el navegador de Anki si lo tienes abierto (limitación conocida de AnkiConnect)
  • Verifica que los nombres del mazo y tipo de nota coincidan exactamente (sensible a mayúsculas)
  • Comprueba que los nombres de los campos coincidan con la configuración de campos de tu tipo de nota

Contribuciones

¡Las contribuciones son bienvenidas! Ya sea que estés corrigiendo errores, agregando funciones o mejorando la documentación, tu ayuda es apreciada.

Cómo Contribuir

  1. Haz un fork del repositorio en GitHub
  2. Clona tu fork localmente: 
    git clone https://github.com/YOUR_USERNAME/anki-mcp.git
cd anki-mcp
  3. Crea una nueva rama para tu función o corrección de errores: 
    git checkout -b feature/your-feature-name
  4. Haz tus cambios y prueba a fondo
  5. Compila y prueba tus cambios: 
    npm install
npm run build
npm run inspector  # Test with MCP Inspector
  6. Haz commit de tus cambios con mensajes claros y descriptivos: 
    git commit -m "Add: description of your changes"
  7. Haz push a tu fork: 
    git push origin feature/your-feature-name
  8. Abre una Solicitud de Extracción (Pull Request) en GitHub con una descripción clara de tus cambios

Pautas de Desarrollo

  • Escribe código TypeScript limpio y legible
  • Sigue el estilo y la estructura de código existentes
  • Prueba tus cambios con el Inspector MCP
  • Actualiza la documentación si estás agregando nuevas funciones
  • Mantén los commits enfocados y atómicos

Reporte de Problemas

¿Encontraste un error o tienes una solicitud de función? Por favor, abre un issue en GitHub con:

  • Un título claro y descriptivo
  • Pasos para reproducir (para errores)
  • Comportamiento esperado vs. real
  • Tu entorno (SO, versión de Anki, versión de Node)

¿Preguntas?

No dudes en abrir un issue para preguntas o únete a la discusión en los issues existentes.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.

Agradecimientos