Anki Model Context Protocol (MCP) Server

Un servidor Model Context Protocol (MCP) de alto rendimiento que permite a los asistentes de IA (Claude Desktop, Claude Code, Antigravity, Codex, Cursor, etc.) gestionar directamente las tarjetas, mazos, tipos de nota, etiquetas, medios y búsquedas de Anki.

⚡ Arquitectura universal de E/S basada en archivos

Las tarjetas modernas (especialmente con marcado HTML, bloques de código con resaltado de sintaxis y fórmulas matemáticas LaTeX) son cargas de gran tamaño. Transmitirlas a través de los parámetros JSON-RPC de las herramientas o devolver el contenido completo de la tarjeta directamente al modelo provoca agotamiento de tokens, salidas truncadas y saturación de la ventana de contexto.

Este servidor implementa Entrada y Salida Universal basada en archivos (File-Based I/O):

1. Wcero exceso de tokens en banda: Las mutaciones, consultas, búsquedas e introspecciones de esquema de tarjetas aceptan rutas de archivos JSON de entrada y escriben toda la salida estructurada en el disco.

2. Respuestas de telemetría compactas: Cada llamada a una herramienta devuelve resúmenes de metadatos acotados ($< 150$ tokens) con el estado, los IDs, los recuentos afectados y la ruta resuelta del output_file.

3. Ingesta atómica por lotes: Se pueden escribir cientos de tarjetas en una única carga útil JSON e ingerirlas en una transacción SQLite atómica en milisegundos.

4. Almacenamiento temporal multiplataforma: Las salidas se colocan por defecto en el directorio temporal del sistema operativo (%TEMP%\anki_mcp en Windows, /tmp/anki_mcp en Linux/macOS) y se pueden anular mediante ANKI_MCP_OUTPUT_DIR.

Related MCP server: Anki MCP Server

Características

• ⚡ Puente directo rápido: Interactúa directamente con la base de datos de la colección de Anki (collection.anki2) mediante el motor oficial anki de Python, con cero sobrecarga HTTP.

• 🔒 Ciclo de vida de conexión no bloqueante: Utiliza una gestión de contexto de apertura/cierre por solicitud (~2.7ms), por lo que los bloqueos de la base de datos se liberan inmediatamente y Anki Desktop no queda bloqueado.

• 🪟 Multiplataforma: Soporte nativo para Windows, macOS y Linux, con detección automática de la colección en las ubicaciones estándar del sistema.

• 🗂️ Mazos jerárquicos: Soporte completo para la creación de mazos anidados (p. ej., Computer Science::Algorithms::Trees).

• 📝 Formatos de tarjeta enriquecidos: Admite tarjetas estándar/básicas, texto con huecos (Cloze) ({{c1::...}}), campos personalizados y fórmulas matemáticas LaTeX ($...$ y $$...$$).

• 🔍 Motor de consultas: Soporte completo para la sintaxis de búsqueda de Anki (deck:Languages tag:grammar, is:due, added:7, "Recursion").

• 🏷️ Gestión de etiquetas: Etiquetado jerárquico y alta/eliminación masiva de etiquetas.

• 📦 Creación por lotes: Adición de tarjetas por lotes de alto rendimiento en operaciones atómicas mediante cargas útiles JSON.

• 💾 Exportación de mazos: Empaquetado nativo a .apkg, .colpkg y .json.

• 💡 Prompts y recursos de MCP: Recursos integrados (anki://decks, anki://stats) y un prompt estructurado de generación de tarjetas (flashcard_generator).

Instalación y configuración

Este proyecto usa uv para la gestión rápida y reproducible de entornos de Python.

Clonar e instalar

git clone https://github.com/debnath-d/anki-mcp-server.git
cd anki-mcp-server
uv sync

Ejecutar el servidor

uv run anki-mcp-server

Configuraciones de los clientes

1. Claude Desktop

Añade el servidor a 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

Configuración en Windows

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\anki-mcp-server",
        "run",
        "anki-mcp-server"
      ]
    }
  }
}

Configuración en macOS / Linux

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

2. Google Antigravity

Añade a tu configuración de MCP de Antigravity (~/.gemini/config/mcp_config.json):

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

3. Claude Code / Codex / clientes CLI

Inicia Claude Code con el servidor MCP:

claude --mcp-server "uv --directory '/path/to/anki-mcp-server' run anki-mcp-server"

Herramientas MCP disponibles

1. Gestión de mazos

2. Tipos de nota (modelos)

3. Gestión de tarjetas y notas (basada en archivos)

4. Medios, control de estado y exportación

5. Búsqueda y descubrimiento

6. Gestión de etiquetas y estadísticas

Pruebas

Ejecuta la suite de pruebas automatizada y el linter:

ruff check .
uv run python -m unittest discover -s tests

Notas importantes y solución de problemas

1. Bloqueo de la base de datos SQLite: Anki utiliza bloqueos exclusivos de archivos. La aplicación de escritorio de Anki con interfaz gráfica de usuario debe estar cerrada mientras el servidor MCP ejecuta operaciones de escritura para evitar bloqueos de anki.errors.DBError.

2. Detección automática de la ruta de la colección:

   • Windows: Se detecta automáticamente en %APPDATA%\Anki2\<Profile>\collection.anki2 o %LOCALAPPDATA%\Anki2\<Profile>\collection.anki2.

   • macOS: Se detecta automáticamente en ~/Library/Application Support/Anki2/<Profile>/collection.anki2.

   • Linux: Se detecta automáticamente en ~/.local/share/Anki2/<Profile>/collection.anki2.

   • Para utilizar una ubicación personalizada, configura la variable de entorno ANKI_COLLECTION_PATH.

3. Caché de salida: Las salidas de las herramientas se almacenan en el directorio temporal de tu sistema operativo (%TEMP%\anki_mcp o /tmp/anki_mcp) por defecto. Configura ANKI_MCP_OUTPUT_DIR para usar un directorio personalizado.