Anki MCP Server

anki-mcp-server

Lee esto en otros idiomas: English, 한국어

Un servidor de Protocolo de Contexto de Modelo (MCP) que conecta Claude y Anki, permitiéndote crear, gestionar y enriquecer mazos de tarjetas mediante lenguaje natural — sin necesidad de abrir la interfaz de Anki.

Requisitos

• Python 3.9 o superior
• Anki 2.1.x o superior
• Complemento AnkiConnect
• Claude Desktop (o cualquier cliente compatible con MCP)

Instalación

1. Configurar Anki y AnkiConnect

1. Instala Anki.
2. Instala el complemento AnkiConnect:
   • En Anki, ve a Tools > Add-ons > Get Add-ons
   • Ingresa el código 2055492159 y haz clic en Aceptar
   • Reinicia Anki
3. Verifica que funcione visitando http://localhost:8765 — deberías ver AnkiConnect v.6.

2. Instalar anki-mcp-server

git clone https://github.com/dhkim0124/anki-mcp-server.git
cd anki-mcp-server

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt

3. Configurar Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

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

{
  "mcpServers": {
    "anki-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/anki_server.py"]
    }
  }
}

Uso

Con Anki ejecutándose en segundo plano, puedes pedirle a Claude cosas como:

• "Crea un mazo de Python con estilo Code y agrega 10 tarjetas sobre decoradores"
• "Muéstrame mis mazos y sus estadísticas"
• "Busca tarjetas etiquetadas con 'sql' y actualiza la que trata sobre índices"
• "Crea un mazo personalizado en modo oscuro con campos: Palabra, Definición, Ejemplo, Audio"
• "Sube esta imagen y adjúntala a una nueva tarjeta en mi mazo de Biología"
• "Sincroniza mi colección con AnkiWeb"

El servidor guía la conversación — hace preguntas aclaratorias sobre el mazo, el estilo y el tipo de tarjeta antes de crear cualquier cosa, y siempre pide confirmación antes de operaciones destructivas.

Herramientas Disponibles

Gestión de Mazos

Herramienta	Descripción
list_decks	Lista todos los mazos con estadísticas (total, nuevas, pendientes, tarjetas en aprendizaje)
create_deck	Crea un nuevo mazo (admite mazos anidados con ::)
delete_deck	Elimina un mazo — requiere confirmación explícita

Operaciones con Tarjetas

Herramienta	Descripción
create_card	Crea una sola tarjeta Básica (frente/dorso)
create_card_batch	Crea múltiples tarjetas en una sola llamada
create_card_custom	Crea una tarjeta usando un tipo de nota personalizado, con adjuntos opcionales de audio/imagen
search_cards	Busca usando la sintaxis de consulta de Anki (etiquetas, texto, filtros de mazo)
update_card	Edita campos y etiquetas de una tarjeta existente
delete_cards	Elimina una o más tarjetas — requiere confirmación explícita

Tipos de Nota y Estilos

Herramienta	Descripción
create_note_type	Crea un tipo de nota personalizado con campos elegidos, estilo CSS y plantillas HTML
get_note_types	Lista todos los tipos de nota disponibles y sus campos
update_note_type_style	Actualiza el CSS de un tipo de nota existente
update_note_type_template	Actualiza las plantillas HTML de un tipo de nota existente

Medios y Sincronización

Herramienta	Descripción
add_media	Sube un archivo de imagen o audio (base64) a la carpeta de medios de Anki
sync_anki	Sincroniza tu colección local con AnkiWeb

Plantillas de Estilo

Cuatro estilos integrados están disponibles mediante el parámetro style en create_note_type:

Estilo	Clave	Mejor para
Predeterminado	"default"	Uso general
Duolingo	"duolingo"	Aprendizaje de idiomas, sensación gamificada
Modo Oscuro	"dark"	Estudiar de noche, reduce la fatiga visual
Code	"code"	Programación, algoritmos
Personalizado	"custom"	Control total — tú proporcionas el CSS

Para estilo personalizado, describe lo que quieres en lenguaje natural y Claude genera el CSS:

"Fondo azul oscuro, acentos verde menta, animación suave de desvanecimiento"

Todo CSS personalizado se valida para bloquear URLs javascript:, etiquetas <script> y manejadores de eventos en línea antes de enviarse a Anki.

Estructura del Proyecto

anki-mcp-server/
├── anki_server.py      # MCP tool definitions and AnkiConnect client
├── config.py           # Constants: URL, API version, media limits
├── instructions.py     # LLM system instructions for conversational behavior
├── templates.py        # Built-in CSS themes, CSS validation, HTML generators
└── tests/
    ├── test_anki_server.py   # Tests for all tools (mocked AnkiConnect)
    └── test_templates.py     # Tests for template logic and CSS validation

Ejecutar Pruebas

pip install pytest pytest-asyncio
pytest tests/ -v

Todas las pruebas simulan AnkiConnect mediante httpx — no se requiere una instancia de Anki en ejecución.

Solución de Problemas

• Anki debe estar abierto: El servidor MCP requiere que Anki esté ejecutándose.
• AnkiConnect no responde: Visita http://localhost:8765 para confirmar que está activo.
• Firewall de Windows: Es posible que debas permitir que Anki pase el firewall para que AnkiConnect funcione.
• Reinicia todo: Si los problemas persisten, reinicia Anki, Claude Desktop y vuelve a verificar la ruta del archivo de configuración.

Contribuciones

Haz un fork del repositorio y abre una solicitud de extracción. Las contribuciones son bienvenidas en:

• Nuevos tipos de tarjetas o estilos de plantilla
• Soporte de idiomas adicionales
• Mejoras de interfaz y experiencia de usuario
• Documentación

Licencia

Licencia MIT — consulta LICENSE para más detalles.