Anki MCP Server

Interactúa con la aplicación de tarjetas de memoria Anki a través del complemento AnkiConnect. Admite generación de audio y búsqueda por similitud.

GitHub
7
Prueba este MCPPatrocinado

Documentación

Anki MCP Server

Un servidor FastMCP para interactuar con Anki a través del Protocolo de Contexto de Modelo (MCP). Este servidor proporciona herramientas completas para gestionar mazos, notas y tipos de notas de Anki, con funciones avanzadas que incluyen generación de audio impulsada por IA, operaciones masivas y búsqueda de similitud semántica.

APIs Externas Utilizadas

Este proyecto se integra con varias APIs externas para proporcionar funcionalidad mejorada:

Google Cloud Text-to-Speech API

  • Propósito: Generación de audio de alta calidad a partir de texto utilizando las voces Chirp de Google
  • Caso de uso: Generar archivos de audio de pronunciación para tarjetas de memoria
  • Características: Voces de calidad HD con pronunciación natural, especialmente excelentes para chino
  • Configuración: Requiere la variable de entorno GOOGLE_CLOUD_API_KEY

AnkiConnect API (Local)

  • Propósito: Interfaz con la aplicación de escritorio de Anki
  • Caso de uso: Todas las operaciones de Anki (crear/leer/actualizar notas, gestionar mazos, etc.)
  • Características: Funcionalidad completa de Anki a través de la API HTTP
  • Configuración: El complemento AnkiConnect debe estar instalado y Anki debe estar en ejecución

Configuración

  1. Instala las dependencias usando uv:

    uv sync

  2. Asegúrate de que Anki esté en ejecución con el complemento AnkiConnect instalado:

    • En Anki, ve a Herramientas > Complementos > Obtener complementos
    • Introduce el código: 2055492159
    • Reinicia Anki

  3. (Opcional) Configura la clave de API para la generación de audio:

    # For audio generation with Google Cloud TTS
export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

  4. Ejecuta el servidor:

    uv run server.py

Integración con Claude Desktop

Para usar este servidor MCP con Claude Desktop, añade la siguiente configuración a tu archivo claude_desktop_config.json:

Ubicación de la configuración

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

Ejemplo de configuración

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ],
      "env": {
        "GOOGLE_CLOUD_API_KEY": "your-google-cloud-api-key-here"
      }
    }
  }
}

Pasos de configuración

  1. Asegúrate de que las dependencias estén instaladas: Asegúrate de haber ejecutado uv sync en tu directorio anki-mcp
  2. Encuentra tu archivo de configuración en la ubicación anterior (críalo si no existe)
  3. Actualiza la ruta: Reemplaza /path/to/your/anki-mcp/ con la ruta real a tu directorio anki-mcp
  4. Añade tu clave de API:
    • Reemplaza your-google-cloud-api-key-here con tu clave de API real de Google Cloud (para la generación de audio)
  5. Reinicia Claude Desktop para que los cambios surtan efecto

Notas importantes

  • Asegúrate de que Anki esté en ejecución con el complemento AnkiConnect antes de usar las herramientas
  • El comando uv gestionará automáticamente el entorno de Python y las dependencias
  • Asegúrate de que uv esté instalado en tu sistema (curl -LsSf https://astral.sh/uv/install.sh | sh)

Alternativa: Usar variables de entorno

Si prefieres mantener tu clave de API en el entorno de tu shell, puedes omitir la sección env:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ]
    }
  }
}

Luego establece la variable de entorno en tu shell:

export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

Verificación

Una vez configurado, reinicia Claude Desktop y deberías ver las herramientas de Anki MCP disponibles en tus conversaciones. Puedes verificar pidiendo a Claude que liste tus mazos de Anki o probando cualquiera de las herramientas disponibles.

Herramientas Disponibles

list_decks

Lista todos los mazos de Anki disponibles con su recuento.

Parámetros: Ninguno

Devuelve: Cadena formateada con todos los nombres de mazos y el recuento total

get_deck_notes

Recupera todas las notas/tarjetas de un mazo específico con información detallada.

Parámetros:

  • deck_name (str): Nombre del mazo de Anki del que recuperar notas

Devuelve: Información detallada sobre todas las notas, incluidos el nombre del modelo, las etiquetas y los valores de los campos

get_deck_sample

Obtiene una muestra aleatoria de notas de un mazo para comprender la estructura típica de las notas.

Parámetros:

  • deck_name (str): Nombre del mazo de Anki del que muestrear notas
  • sample_size (int, opcional): Número de notas a muestrear (1-50, predeterminado: 5)

Devuelve: Información detallada sobre las notas muestreadas

get_deck_note_types

Analiza un mazo para identificar todos los tipos de notas (modelos) y sus definiciones de campos.

Parámetros:

  • deck_name (str): Nombre del mazo de Anki a analizar

Devuelve: Todos los tipos de notas únicos utilizados en el mazo con sus nombres de campos

create_note

Crea una nueva nota en el mazo especificado.

Parámetros:

  • deck_name (str): Nombre del mazo de Anki al que añadir la nota
  • model_name (str): Nombre del tipo de nota/modelo a utilizar
  • fields (dict): Diccionario que asigna nombres de campos a valores (p. ej., {'Front': 'Question', 'Back': 'Answer'})
  • tags (list, opcional): Lista opcional de etiquetas para añadir a la nota

Devuelve: Objeto JSON con noteId y estado de éxito o mensaje de error

update_note

Actualiza campos específicos de una nota existente conservando los demás campos.

Parámetros:

  • note_id (int): ID de la nota a actualizar
  • fields (dict): Diccionario que asigna nombres de campos a nuevos valores (p. ej., {'Audio': '[sound:pronunciation.mp3]'})
  • tags (list, opcional): Lista opcional de etiquetas para reemplazar las etiquetas existentes

Devuelve: Objeto JSON con estado de éxito e información de campos actualizados

Caso de uso: Perfecto para añadir archivos de audio a tarjetas existentes o actualizar contenido específico

create_deck_with_note_type

Crea un nuevo mazo y, opcionalmente, un nuevo tipo de nota con campos y plantillas personalizados.

Parámetros:

  • deck_name (str): Nombre para el nuevo mazo de Anki
  • model_name (str): Nombre para el tipo de nota/modelo
  • fields (list): Lista de nombres de campos (p. ej., ['Front', 'Back', 'Extra'])
  • card_templates (list, opcional): Lista opcional de definiciones de plantillas de tarjetas

Devuelve: Objeto JSON con estado de creación y detalles

list_note_types

Lista todos los tipos de notas (modelos) disponibles con información completa.

Parámetros: Ninguno

Devuelve: Información sobre todos los tipos de notas, incluidos campos, plantillas y estilos

generate_audio

Genera archivos de audio de alta calidad a partir de texto utilizando la API de Text-to-Speech de Google Cloud con voces Chirp.

Parámetros:

  • text (str): Texto a convertir en voz
  • language (str, opcional): Código de idioma (predeterminado: "cmn-cn" para chino)
  • voice (str, opcional): Nombre de la voz (predeterminado: "cmn-CN-Chirp3-HD-Achernar" para voz HD en chino)

Devuelve: Objeto JSON con datos de audio MP3 codificados en base64 y metadatos

Configuración: Requiere la variable de entorno GOOGLE_CLOUD_API_KEY

Características: Voces de calidad HD con pronunciación natural, especialmente excelentes para el aprendizaje del idioma chino

save_media_file

Guarda datos multimedia codificados en base64 como archivo en la colección multimedia de Anki para su uso en tarjetas.

Parámetros:

  • filename (str): Nombre del archivo a guardar (p. ej., 'audio.mp3', 'image.jpg')
  • base64_data (str): Datos del archivo codificados en base64
  • media_type (str, opcional): Tipo de archivo multimedia (predeterminado: "audio")

Devuelve: Objeto JSON con nombre de archivo guardado y estado de éxito

Caso de uso: Guarda audio generado u otros archivos multimedia para su uso en tarjetas de Anki

generate_and_save_audio

Genera audio a partir de texto y lo guarda directamente en la colección multimedia de Anki en una sola operación.

Parámetros:

  • text (str): Texto a convertir en voz y guardar
  • filename (str): Nombre para el archivo de audio (p. ej., 'pronunciation.mp3')
  • language (str, opcional): Código de idioma (predeterminado: "cmn-cn" para chino)
  • voice (str, opcional): Nombre de la voz (predeterminado: "cmn-CN-Chirp3-HD-Achernar")

Devuelve: Objeto JSON con nombre de archivo y etiqueta de sonido para usar en campos de tarjetas

Configuración: Requiere la variable de entorno GOOGLE_CLOUD_API_KEY

Caso de uso: Generación y guardado de audio en un solo paso, devuelve la etiqueta [sound:filename.mp3] lista para campos de tarjetas

create_notes_bulk

Crea múltiples notas en una sola operación por lotes para máxima eficiencia. Gestiona los duplicados con elegancia informando qué notas son duplicados mientras sigue creando las notas no duplicadas. NUEVO: Opcionalmente, genera automáticamente archivos de audio usando Google TTS para cada nota.

Parámetros:

  • deck_name (str): Nombre del mazo de Anki al que añadir notas

  • notes_list (list): Lista de diccionarios de notas, cada uno con 'model_name', 'fields' y, opcionalmente, 'tags'

  • auto_audio (AutoAudioConfig o null, opcional): IMPORTANTE: Pásalo como diccionario/objeto con la estructura que se muestra a continuación, NO como cadena JSON. Configuración para la generación automática de audio:

    • enabled (bool, obligatorio): Debe ser true para habilitar la generación de audio
    • source_field (str, obligatorio): Nombre del campo del que leer el texto (p. ej., "Front", "Hanzi")
    • target_field (str, obligatorio): Nombre del campo en el que escribir la etiqueta de audio (p. ej., "Audio")
    • language (str, opcional): Código de idioma: predeterminado "cmn-cn" para chino
    • voice (str, opcional): Nombre de la voz: predeterminado "cmn-CN-Chirp3-HD-Achernar"

    Formato correcto (objeto diccionario):

    {
  "enabled": true,
  "source_field": "Hanzi",
  "target_field": "Audio",
  "language": "cmn-cn",
  "voice": "cmn-CN-Chirp3-HD-Achernar"
}

    INCORRECTO: no lo pases como cadena:

    "{\"enabled\": true, \"source_field\": \"Hanzi\", ...}"  ❌ INCORRECT

    Para deshabilitar la generación de audio, pasa null u omite este parámetro por completo.

Devuelve: Objeto JSON con recuentos de éxito/fallo, matriz de notas exitosas, matriz de notas fallidas y resultados de generación de audio si está habilitada

Características:

  • Utiliza canAddNotesWithErrorDetail para verificar previamente qué notas se pueden añadir
  • Solo intenta añadir notas válidas, garantizando que no haya fallos en el lote
  • Proporciona informes de error detallados para cada nota fallida (duplicados, errores de validación, etc.)
  • Devuelve los IDs de las notas creadas correctamente para su posterior procesamiento
  • Genera automáticamente archivos de audio para todas las notas en una sola operación: ¡no es necesario crear notas y luego actualizarlas por separado!
  • La generación de audio informa del éxito/fallo de cada nota individualmente
  • Omite la generación de audio si el campo de destino ya tiene contenido

Caso de uso: Crea 20 tarjetas de vocabulario chino con audio en una sola operación eficiente en lugar de crear tarjetas y luego actualizar cada una individualmente

update_notes_bulk

Actualiza múltiples notas en una sola operación por lotes para máxima eficiencia.

Parámetros:

  • updates (list): Lista de diccionarios de actualización, cada uno con 'note_id', diccionario 'fields' y, opcionalmente, lista 'tags'

Devuelve: Objeto JSON con recuentos de éxito/fallo y resultados de actualización detallados

Caso de uso: Perfecto para actualizaciones por lotes, como añadir archivos de audio a múltiples tarjetas a la vez

find_similar_notes

Encuentra notas que contengan el texto de búsqueda como subcadena en cualquier campo. Coincidencia de texto simple y fiable.

Parámetros:

  • deck_name (str): Nombre del mazo de Anki en el que buscar
  • search_text (str): Texto a buscar como subcadena en cualquier campo
  • case_sensitive (bool, opcional): Si la búsqueda debe distinguir entre mayúsculas y minúsculas (predeterminado: false)
  • max_results (int, opcional): Número máximo de notas coincidentes a devolver (predeterminado: 20)

Devuelve: Objeto JSON con notas coincidentes y detalles sobre qué campos contenían el texto de búsqueda

Características:

  • Coincidencia rápida de subcadenas en todos los campos de notas
  • Opciones de búsqueda que distinguen o no entre mayúsculas y minúsculas
  • Muestra exactamente qué campos coincidieron con los criterios de búsqueda
  • No requiere dependencias de API externas

Detalles Técnicos

  • Framework: FastMCP (construido sobre FastAPI)
  • Nombre del servidor: "anki-mcp"
  • URL de AnkiConnect: http://localhost:8765
  • Dependencias: fastapi, fastmcp, requests, uvicorn
  • APIs externas:
    • Google Cloud Text-to-Speech API (para generación de audio)
  • Formato de audio: MP3 con codificación base64

Características

  • Generación de audio HD: TTS de calidad premium con voces Google Cloud Chirp, optimizado para la pronunciación en chino
  • Generación automática de audio en lote: Crea notas con audio en una sola operación: ¡no es necesario crear notas y luego agregar audio por separado!
  • Actualización de notas: Actualiza notas existentes con contenido nuevo, como archivos de audio, conservando otros campos
  • Gestión de medios: Integración directa con la colección de medios de Anki para un manejo fluido de archivos
  • Operaciones en lote: Creación y actualización eficiente de notas en lote para conjuntos de datos grandes
  • Búsqueda rápida de texto: Coincidencia simple de subcadenas para encontrar notas que contengan texto específico
  • Manejo integral de errores: Manejo robusto de errores para todas las fallas de API y casos límite
  • Formato inteligente de datos: Truncamiento y formato de contenido para una legibilidad óptima
  • Muestreo aleatorio: Muestreo eficiente para conjuntos de datos grandes sin problemas de memoria
  • Plantillas personalizadas: Soporte completo para plantillas de tarjetas personalizadas y estilos CSS
  • Seguridad de tipos: Validación completa de parámetros con Pydantic
  • Manejo seguro de claves API: Gestión de claves API basada en variables de entorno
  • Manejo robusto de errores: Prevalidación de notas con informes de error detallados para duplicados y otros problemas
  • Soporte multilingüe: Optimizado para el aprendizaje del chino, pero compatible con varios idiomas