Anki MCP Server

Interactúa con el software de tarjetas de memoria Anki usando LLMs a través del complemento AnkiConnect.

Documentación

Servidor MCP de Anki

Un servidor de Model Context Protocol (MCP) que permite a los LLMs interactuar con el software de tarjetas flash Anki a través de AnkiConnect.

Características

Herramientas

anki_check_connection - Verifica si AnkiConnect es accesible
anki_list_decks - Lista todos los mazos de Anki disponibles, opcionalmente con IDs de mazos
anki_create_deck - Crea un nuevo mazo de Anki
anki_list_tags - Lista todas las etiquetas utilizadas actualmente en la colección
anki_add_note_tags - Añade etiquetas a una o más notas
anki_remove_note_tags - Elimina etiquetas de una o más notas
anki_create_note - Crea una nueva nota
anki_batch_create_notes - Crea múltiples notas a la vez
anki_search_notes - Busca notas usando la sintaxis de consulta de Anki
anki_get_note_info - Obtiene información detallada sobre una nota
anki_update_note - Actualiza los campos y/o etiquetas de una nota existente
anki_delete_note - Elimina una o múltiples notas
anki_list_note_types - Lista todos los tipos de nota disponibles
anki_create_note_type - Crea un nuevo tipo de nota
anki_get_note_type_info - Obtiene la estructura detallada de un tipo de nota
anki_sync - Activa la sincronización con AnkiWeb; requiere {"confirm": true} porque una sincronización completa puede fusionar o sobrescribir colecciones locales y remotas. El éxito significa que Anki aceptó la solicitud, no que AnkiWeb recibió los datos; un diálogo de bloqueo en Anki puede mantener la sincronización en cola silenciosamente

Los nombres de herramientas heredados sin prefijo como create_note y list_decks siguen siendo invocables para clientes existentes, pero las nuevas integraciones de agentes deben usar los nombres anki_*.

Recursos

anki://decks/all - Lista completa de mazos disponibles con IDs de mazos
anki://tags/all - Lista completa de etiquetas
anki://note-types/all - Lista de todos los tipos de nota disponibles
anki://note-types/all-with-schemas - Información detallada de la estructura de todos los tipos de nota
anki://note-types/{modelName} - Información detallada de la estructura de un tipo de nota específico

Requisitos previos

Anki instalado en tu sistema
Complemento AnkiConnect instalado en Anki
Node.js 20.11 o más reciente

Configuración

Instalación mediante Extensión de Escritorio (.mcpb)

Este repositorio admite Extensiones de Escritorio de Anthropic (MCPB). La forma más fácil de usar este servidor en Claude Desktop es instalando el paquete .mcpb.

Genera el archivo .mcpb localmente usando el script proporcionado:

npm run mcpb

Abre Configuración de Claude Desktop → Extensiones y arrastra el archivo .mcpb generado, luego haz clic en Instalar.

Esto valida manifest.json y genera un archivo .mcpb que puedes instalar como se indicó. Aprende más sobre Extensiones de Escritorio en el anuncio de Anthropic: Extensiones de Escritorio: instalación de servidores MCP con un clic para Claude Desktop.

Uso con Claude Desktop

Añade el servidor a tu claude_desktop_config.json:

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server"]
    }
  }
}

Uso de un puerto personalizado de AnkiConnect

Si tu AnkiConnect se ejecuta en un puerto diferente, puedes especificarlo usando el parámetro --port:

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server", "--port", "8080"]
    }
  }
}

Configuración para Cline

Añade el servidor al archivo de configuración MCP de Cline dentro de la configuración de VSCode cline_mcp_settings.json

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server"]
    }
  }
}

Uso de un puerto personalizado de AnkiConnect

Para Cline, también puedes especificar un puerto personalizado:

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server", "--port", "8080"]
    }
  }
}

Habilidades del Agente (Claude Code)

Instala la habilidad de Anki para dar a Claude Code conocimiento integrado de todas las herramientas y flujos de trabajo de Anki:

npx skills add nailuoGG/anki-mcp-server@anki

Una vez instalado, Claude Code usará automáticamente la habilidad cuando le pidas crear tarjetas flash, gestionar mazos o importar notas por lotes.

Nota: No uses la versión empaquetada .mcpb como servidor MCP — genera metadatos de Electron en stdout que rompen el protocolo MCP stdio. Usa npx -y anki-mcp-server en su lugar.

Desarrollo

Empaquetado de una Extensión de Escritorio (.mcpb)

Crea un paquete de Extensión de Escritorio distribuible para Claude Desktop:

npm run mcpb

Esto compilará el proyecto y generará un archivo .mcpb desde el repositorio actual, validando manifest.json. Pruébalo arrastrándolo a la configuración de Extensiones de Claude Desktop. Referencia: Extensiones de Escritorio: instalación de servidores MCP con un clic para Claude Desktop.

Publicación en el Registro MCP

Este servidor se publica automáticamente en el Registro MCP cuando se lanza una nueva versión. El proceso de publicación incluye:

CI/CD automatizado: GitHub Actions publica automáticamente tanto en NPM como en el Registro MCP en lanzamientos exitosos
Validación de esquema: El archivo server.json se valida contra el esquema MCP antes de publicar
Sincronización de versiones: Las versiones se mantienen sincronizadas entre package.json, manifest.json y server.json
Pruebas exhaustivas: Pruebas de Node.js multi-versión, linting y validación antes de publicar
Soporte beta: Lanzamientos beta automatizados para probar nuevas funciones

Validación manual

Puedes validar la configuración del servidor MCP localmente:

npm run validate-mcp

Esto descargará el esquema MCP más reciente y validará tu archivo server.json.

Publicación manual

Si necesitas publicar manualmente, puedes usar la CLI del Editor MCP:

# Install MCP Publisher
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
chmod +x mcp-publisher
sudo mv mcp-publisher /usr/local/bin/

# Login to MCP Registry
mcp-publisher login github-oidc

# Publish to MCP Registry
mcp-publisher publish

Configuración

Instala las dependencias:

npm install

Compila el servidor:

npm run build

Para desarrollo con reconstrucción automática:

npm run watch

Pruebas

Ejecuta la suite de pruebas:

npm test

Esto ejecuta pruebas unitarias para esquemas de herramientas MCP, resultados de herramientas estructuradas, creación de notas, flujos de búsqueda/actualización/eliminación y manejo de errores. Estas pruebas usan clientes AnkiConnect simulados; usa MCP Inspector con una instancia de Anki en ejecución para verificaciones de integración manuales.

Evaluaciones MCP

Los activos de evaluación de agentes de solo lectura se encuentran en evals/. Carga el fixture en un perfil de Anki desechable, luego ejecuta las preguntas XML contra el servidor MCP para verificar que los agentes puedan descubrir mazos, etiquetas, esquemas de tipos de nota, recursos y resultados de herramientas estructuradas.

Depuración

Dado que los servidores MCP se comunican a través de stdio, recomendamos usar el MCP Inspector:

npm run inspector

Esto proporciona una interfaz basada en navegador para:

Monitorear mensajes MCP
Probar invocaciones de herramientas
Ver registros del servidor
Depurar problemas de comunicación

Ejemplo de uso

Crea un nuevo mazo:

Create a new Anki deck called "Programming"

Añade una tarjeta básica:

Create an Anki card in the "Programming" deck with:
Front: What is a closure in JavaScript?
Back: A closure is the combination of a function and the lexical environment within which that function was declared.

Añade una tarjeta de eliminación cloze:

Create a cloze card in the "Programming" deck with:
Text: In JavaScript, {{c1::const}} declares a block-scoped variable that cannot be {{c2::reassigned}}.

Elimina una sola nota:

Delete note ID 1234567890

Elimina múltiples notas a la vez:

Delete note IDs 1234567890, 9876543210, and 1122334455

Añade etiquetas a notas:

Add tags "review" and "mcp" to note IDs 1234567890 and 9876543210

Contribuciones

Haz un fork del repositorio
Crea tu rama de características
Ejecuta las pruebas: npm test
Envía una solicitud de extracción

Historial de estrellas

Créditos

Icono cortesía de macOS Icons

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles