Mousetaile

Servidor MCP de Anki

GitHub
17

Documentación

Mousetail Logo

El servidor MCP más simple y estable para Anki

UV Python 3.10+ MCP License: MIT

El objetivo de Mousetail es ser la forma más simple y confiable de conectar Anki a un LLM. No requiere complementos, solo tener Anki instalado y un LLM que desees conectar a tus mazos.

Ejecutar el servidor es tan simple como:

uvx mousetail

Para instrucciones detalladas sobre la integración con Claude Code, Claude Desktop y otras herramientas de LLM:

Guía de uso

Referencia de API

Características

  • Mínimo - soporta operaciones básicas de Anki: crear, leer, actualizar y eliminar
  • Estable - funciona directamente con la API estable pylib de Anki, sin complementos ni dependencias
  • Simple - no requiere configuración, descubre automáticamente tus colecciones de Anki

Casos de uso

Guarda selectivamente lo que aprendes en conversaciones con un LLM en tu memoria

"Crea un mazo basado en nuestra conversación para que no olvide detalles críticos"

Usa un LLM para interactuar con tu mazo

"Crea una tarjeta - ¿qué es un coeficiente?, crea una tarjeta - identifica el primer coeficiente en este polinomio"

Usa un LLM para limpiar un mazo

"Revisa mi mazo de vocabulario francés para verificar su corrección y corrige cualquier error, errata o fallo"

Sincronización

Mousetail admite la sincronización de tu colección de Anki con AnkiWeb o un servidor de sincronización autoalojado. Esto te permite mantener tu colección sincronizada entre dispositivos.

Inicio rápido

Sincroniza con AnkiWeb (guarda las credenciales para futuras sincronizaciones):

> "Save my AnkiWeb credentials: username is myuser@example.com and password is mypassword"
> "Sync my collection with AnkiWeb"

Gestión de credenciales

Mousetail almacena las credenciales de forma segura en el gestor de credenciales de tu sistema:

  • macOS: Llavero
  • Windows: Administrador de credenciales
  • Linux: Servicio de secretos (GNOME Keyring, KWallet, etc.)

Herramientas de credenciales disponibles:

  • save_sync_credentials - Guarda nombre de usuario/contraseña de forma segura
  • load_sync_credentials - Carga credenciales guardadas
  • delete_sync_credentials - Elimina credenciales guardadas

Opciones de sincronización

La herramienta sync_collection admite:

  • Sincronización con AnkiWeb (predeterminada) - Deja el endpoint vacío
  • Servidores autoalojados - Proporciona una URL de endpoint personalizada (p. ej., https://sync.example.com)
  • Sincronización de medios - Habilitada por defecto, incluye imágenes y archivos de audio
  • Sincronización solo de colección - Establece sync_media: false para omitir medios

Ejemplos

Configuración inicial con AnkiWeb:

> "Save my sync credentials for AnkiWeb - username: user@example.com, password: mypass123"
> "Sync my collection"

Uso de un servidor autoalojado:

> "Save my sync credentials - username: john, password: secret, endpoint: https://sync.myserver.com"
> "Sync my collection"

Sincronización única sin guardar credenciales:

> "Sync my collection with AnkiWeb using username user@example.com and password mypass123"

Sincronización solo de colección (omitir medios):

> "Sync my collection but don't sync media files"

Configuración

Puedes establecer un endpoint de sincronización predeterminado en config.json:

{
  "sync": {
    "endpoint": "https://sync.example.com"
  }
}

Deja endpoint como null para usar AnkiWeb por defecto.

Notas importantes

  • Cierra Anki primero: La sincronización fallará si la aplicación de Anki está en ejecución
  • Sincronización de medios: La sincronización de medios es más lenta y usa más ancho de banda, pero garantiza que las imágenes/audio se sincronicen
  • Conflictos: Si ocurren conflictos, intenta sincronizar desde el escritorio de Anki primero para resolverlos
  • Seguridad: Las credenciales nunca se almacenan en texto plano; se guardan en el almacenamiento seguro de credenciales de tu sistema

Configuración del servidor de sincronización autoalojado

Para sincronizar con tu propio servidor:

  1. Configura un servidor de sincronización de Anki
  2. Configura las credenciales en el servidor (usando variables de entorno como SYNC_USER1=user:password)
  3. Guarda tus credenciales en Mousetail con el endpoint del servidor
  4. Sincroniza normalmente

Para una configuración detallada del servidor de sincronización, consulta la documentación oficial de Anki.

Notas importantes

Cómo se accede a las colecciones

El servidor MCP encuentra las colecciones de Anki en sus ubicaciones estándar:

  • macOS: ~/Library/Application Support/Anki2/[Profile]/collection.anki2
  • Linux: ~/.local/share/Anki2/[Profile]/collection.anki2
  • Windows: %APPDATA%\Anki2\[Profile]\collection.anki2

No necesitas configurar rutas: el servidor descubre automáticamente las colecciones disponibles. Esto se puede personalizar mediante la configuración.

Configuración

El servidor se puede personalizar mediante un archivo config.json. Consulta la Guía de uso para las opciones de configuración.

Desarrollo

Configuración de desarrollo local

Para desarrollar y probar Mousetail localmente con Claude Code:

  1. Clona el repositorio:

    git clone https://github.com/listfold/mousetail.git
cd mousetail

  2. Instala las dependencias:

    uv sync

  3. Configura Claude Code: El proyecto incluye un archivo .mcp.json que configura el servidor MCP para el desarrollo local:

    {
  "mcpServers": {
    "mousetail": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "mousetail.mcp.stdio_server"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

  4. Reinicia Claude Code: Después de que la configuración esté en su lugar, reinicia Claude Code para cargar el servidor MCP.

  5. Verifica el servidor:

    • Usa /context en Claude Code para ver las herramientas MCP disponibles
    • El servidor mousetail debería aparecer con todas las herramientas disponibles (list_collections, create_note, sync_collection, etc.)

  6. Prueba la funcionalidad de sincronización:

    • Cierra la aplicación de escritorio de Anki antes de probar
    • Prueba la gestión de credenciales: save_sync_credentials, load_sync_credentials, delete_sync_credentials
    • Prueba la sincronización: sync_collection con tus credenciales de AnkiWeb o servidor autoalojado

Objetivos principales

Mousetail fue creado porque todas las herramientas MCP de Anki existentes dependen del complemento AnkiConnect.

AnkiConnect es un servidor HTTP para Anki, creado originalmente para admitir la conexión de extensiones de navegador como yomichan a Anki. Para el desarrollo de MCP, no es necesario e introduce problemas:

  • introduce complejidad, p. ej., un servidor HTTP dedicado para Anki ocupa un puerto
  • introduce riesgo, p. ej., si la API de AnkiConnect cambia o tiene un error, la herramienta MCP fallará
  • introduce un paso adicional, p. ej., todas las herramientas MCP actuales requieren instalar el complemento AnkiConnect

Mousetail tiene un enfoque mucho más simple. Se integra directamente con pylib de Anki. Esta es una API estable que forma parte del núcleo de Anki, por lo tanto, no está sujeta a cambios arbitrarios o frecuentes y no requiere complementos de terceros.

Debido a que prioriza la simplicidad, mousetail seguirá siendo más estable que las alternativas. La compensación es que Mousetail nunca se integrará con la interfaz de usuario de Anki. También es razonable asumir que Mousetail solo funcionará con herramientas LLM y mazos de Anki ubicados en el mismo sistema.

Construcción de documentación

El proyecto usa Sphinx con el tema Furo para generar documentación a partir de docstrings de Python.

  1. Instala las dependencias de documentación:

    uv pip install ".[docs]"

  2. Construye la documentación:

    uv run python -m sphinx -b html docs docs/_build/html

  3. Visualiza la documentación: Abre docs/_build/html/index.html en tu navegador.

La documentación se construye y despliega automáticamente en GitHub Pages en cada push a la rama principal.

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.