Clanki - Claude's Anki Integration

Permite que los asistentes de IA interactúen con mazos de tarjetas de memoria de Anki a través del plugin AnkiConnect.

Documentación

Clanki - Claude's Anki Integration

Un servidor MCP que permite a asistentes de IA como Claude interactuar con mazos de tarjetas de Anki a través del Protocolo de Contexto de Modelo (MCP).

Características

Crear y gestionar mazos de Anki
Crear notas básicas con contenido frontal/trasero
Crear notas de cloze
Crear muchas notas a la vez en una sola solicitud
Adjuntar imágenes y audio desde URLs - descargados e incrustados automáticamente
Soporte de formato HTML en los campos de las notas
Actualizar notas existentes y eliminaciones de cloze
Añadir y gestionar etiquetas
Buscar notas con la sintaxis de consulta de Anki
Eliminar notas permanentemente
Ver el contenido de los mazos e información de las notas
Integración completa con AnkiConnect

Requisitos previos

Anki instalado y en ejecución
Plugin AnkiConnect instalado en Anki
Node.js 16 o superior

Instalación

Clona este repositorio:

git clone https://github.com/yourusername/clanki.git
cd clanki

Instala las dependencias:

npm install

Compila el proyecto:

npm run build

Configuración

Asegúrate de que Anki esté en ejecución y el plugin AnkiConnect esté instalado y habilitado.
Anota la ruta absoluta a build/index.js en tu checkout de clanki. Cada cliente a continuación la necesita, y ninguno acepta una ruta relativa — no se ejecutan desde tu directorio de proyecto, por lo que ./build/index.js no se resolverá.
```
# from the clanki directory
node -e "console.log(require('path').resolve('build/index.js'))"
```
En Windows esto imprime barras invertidas. Están bien tal cual para los dos comandos CLI a continuación, pero deben duplicarse o cambiarse por barras normales si pegas la ruta en una configuración JSON — consulta la nota de Claude Desktop.
Registra el servidor con tu cliente, usando una de las secciones a continuación.
Verifica que el servidor pueda alcanzar Anki. Con Anki en ejecución:

curl -X POST http://127.0.0.1:8765 -d "{\"action\":\"version\",\"version\":6}"

Una configuración funcional responde {"result": 6, "error": null}. Si no lo hace, consulta docs/troubleshooting.md — los fallos de conexión son, con mucho, el problema más común, y la configuración predeterminada de AnkiConnect no necesita cambios.

Claude Desktop

Edita claude_desktop_config.json:

Plataforma	Ubicación
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "clanki": {
      "command": "node",
      "args": ["/absolute/path/to/clanki/build/index.js"]
    }
  }
}

Reemplaza /absolute/path/to/clanki con la ruta real a tu instalación de clanki. En Windows, escribe la ruta con barras normales o barras invertidas escapadas (C:\\Users\\you\\clanki\\build\\index.js) — una barra invertida simple es un carácter de escape en JSON y no se analizará.

Reinicia Claude Desktop después; lee la configuración solo al iniciar.

Claude Code

claude mcp add clanki -- node /absolute/path/to/clanki/build/index.js

El -- es obligatorio. Marca el final de las opciones propias de claude mcp add, por lo que todo lo que sigue se trata como el comando a lanzar. Sin él, los argumentos se analizan como opciones para claude mcp add y obtienes una entrada rota en lugar de un error.

Por defecto, esto registra el servidor solo en el proyecto actual (--scope local). Hay otros dos ámbitos disponibles:

Ámbito	Qué hace
`--scope local`	Tú, solo en este proyecto. El predeterminado.
`--scope user`	Tú, en todos los proyectos de esta máquina.
`--scope project`	Escrito en `.mcp.json` en la raíz del repositorio, para confirmarlo y que los compañeros también lo tengan.

Comprueba que funcionó:

claude mcp list

clanki debería aparecer como conectado. Si aparece como fallo de conexión, claude mcp get clanki muestra el error.

También puedes escribir .mcp.json manualmente, usando la misma forma que la configuración de Claude Desktop anterior. Claude Code lo lee al inicio de la sesión, así que reinicia la sesión después de editarlo.

Codex

codex mcp add clanki -- node /absolute/path/to/clanki/build/index.js

Al igual que con Claude Code, el -- separa las opciones propias de Codex del comando que lanza el servidor, y es obligatorio.

Esto escribe en ~/.codex/config.toml. Codex usa TOML en lugar de JSON, así que si prefieres editar el archivo directamente, la entrada se ve así:

[mcp_servers.clanki]
command = "node"
args = ["/absolute/path/to/clanki/build/index.js"]

Ten en cuenta que la tabla TOML es mcp_servers con guion bajo, no mcpServers como en las configuraciones JSON anteriores.

Lista los servidores configurados con:

codex mcp list

Configuración

Clanki no necesita configuración en una instalación normal. Cada variable a continuación es opcional.

Usar Anki en un idioma distinto del inglés

Anki traduce los nombres de sus tipos de nota integrados, y sus campos, cuando se crea una colección — una colección en alemán tiene Einfach con los campos Vorderseite y Rückseite, no Basic con Front y Back. Clanki los encuentra por su estructura en lugar de por sus nombres, por lo que esto funciona sin configuración en cualquier idioma que uses.

Si tu colección contiene varios tipos de nota que se parecen, Clanki no puede saber cuál querías. Se detiene y lista los candidatos en lugar de adivinar, porque adivinar mal escribiría tu texto en un campo que no existe, y Anki lo descarta sin error. Nombra el que quieras:

Variable	Qué hace
`CLANKI_BASIC_NOTE_TYPE`	Tipo de nota para notas ordinarias de dos caras, p. ej. `Einfach`
`CLANKI_CLOZE_NOTE_TYPE`	Tipo de nota para notas de cloze, p. ej. `Lückentext`
`CLANKI_BASIC_FIELDS`	Sus dos campos, frontal primero, p. ej. `Vorderseite,Rückseite`
`CLANKI_CLOZE_FIELDS`	Sus dos campos, texto primero, p. ej. `Text,Extra`

Nombrar el tipo de nota suele ser suficiente — Clanki lee sus campos de tu colección en orden. Las variables _FIELDS solo se necesitan para un tipo de nota cuyos campos no están en orden frontal-luego-trasero. Ambas se verifican contra tu colección al iniciar, por lo que un error tipográfico se informa en lugar de perder contenido silenciosamente.

Conectarse a AnkiConnect en otro lugar

Variable	Predeterminado
`CLANKI_ANKI_CONNECT_URL`	`http://127.0.0.1:8765`

Establece esto solo si cambiaste el puerto de AnkiConnect o alcanzas Anki en otra máquina.

Dónde van las variables depende de tu cliente.

En las configuraciones JSON (Claude Desktop, y .mcp.json para Claude Code), van en un bloque env junto a command y args:

{
  "mcpServers": {
    "clanki": {
      "command": "node",
      "args": ["/path/to/clanki/build/index.js"],
      "env": {
        "CLANKI_BASIC_NOTE_TYPE": "Einfach"
      }
    }
  }
}

En ~/.codex/config.toml, van en una sub-tabla env bajo el servidor:

[mcp_servers.clanki]
command = "node"
args = ["/path/to/clanki/build/index.js"]

[mcp_servers.clanki.env]
CLANKI_BASIC_NOTE_TYPE = "Einfach"

Ambos CLI pueden establecerlas al registrar el servidor, con --env repetido una vez por variable:

claude mcp add clanki --env CLANKI_BASIC_NOTE_TYPE=Einfach -- node /path/to/clanki/build/index.js

codex mcp add clanki --env CLANKI_BASIC_NOTE_TYPE=Einfach -- node /path/to/clanki/build/index.js

Reinicia el servidor después de cambiarlas.

Herramientas Disponibles

create-deck

Crea un nuevo mazo de Anki

Parámetros:
- name: Nombre para el nuevo mazo

create-card

Crea una nueva nota en un mazo especificado. Soporta formato HTML y adjuntos multimedia.

Parámetros:
- deckName: Nombre del mazo al que añadir la nota
- front: Contenido del lado frontal de la nota (soporta HTML)
- back: Contenido del lado trasero de la nota (soporta HTML)
- tags: (Opcional) Matriz de etiquetas para la nota
- frontImages: (Opcional) Matriz de URLs de imágenes para el frontal
- backImages: (Opcional) Matriz de URLs de imágenes para el trasero
- frontAudio: (Opcional) Matriz de URLs de audio para el frontal
- backAudio: (Opcional) Matriz de URLs de audio para el trasero

create-cloze-card

Crea una nueva nota de cloze en un mazo especificado. Soporta formato HTML y adjuntos multimedia.

Parámetros:
- deckName: Nombre del mazo al que añadir la nota
- text: Texto que contiene eliminaciones de cloze usando la sintaxis {{c1::texto}} (soporta HTML)
- backExtra: (Opcional) Información extra para mostrar en el trasero de la tarjeta (soporta HTML)
- tags: (Opcional) Matriz de etiquetas para la nota
- textImages: (Opcional) Matriz de URLs de imágenes para el campo de texto
- backImages: (Opcional) Matriz de URLs de imágenes para el campo extra del trasero
- textAudio: (Opcional) Matriz de URLs de audio para el campo de texto
- backAudio: (Opcional) Matriz de URLs de audio para el campo extra del trasero

create-cards-bulk

Crea muchas notas básicas en una sola solicitud. Prefiere esto sobre llamadas repetidas a create-card para un lote: envía una sola solicitud a Anki independientemente del tamaño. No soporta multimedia — usa create-card para notas que necesiten imágenes o audio.

Parámetros:
- deckName: Nombre del mazo al que añadir las notas
- cards: Matriz de objetos { front, back, tags? } (al menos uno)

El addNotes de Anki es todo-o-nada — un solo duplicado fallaría todo el lote — por lo que la herramienta pregunta qué notas se pueden añadir primero y envía solo esas. La respuesta informa cuántas se añadieron, y la posición de entrada y la razón propia de Anki para cada nota omitida, para que puedas corregir y reenviar solo esas.

create-cloze-cards-bulk

Crea muchas notas de cloze en una sola solicitud. Mismas ventajas y desventajas que create-cards-bulk; usa create-cloze-card cuando necesites multimedia.

Parámetros:
- deckName: Nombre del mazo al que añadir las notas
- cards: Matriz de objetos { text, backExtra?, tags? } (al menos uno)

La sintaxis de cloze se valida para todo el lote antes de enviar nada, por lo que una entrada malformada falla la llamada en lugar de dejar un lote parcial en el mazo.

update-card

Actualiza una nota existente

Parámetros:
- noteId: ID de la nota a actualizar
- front: (Opcional) Nuevo contenido del lado frontal
- back: (Opcional) Nuevo contenido del lado trasero
- tags: (Opcional) Nuevas etiquetas para la nota

update-cloze-card

Actualiza una nota de cloze existente

Parámetros:
- noteId: ID de la nota a actualizar
- text: (Opcional) Nuevo texto con eliminaciones de cloze
- backExtra: (Opcional) Nueva información extra para el trasero
- tags: (Opcional) Nuevas etiquetas para la nota

find-cards

Busca notas con la sintaxis de consulta de Anki y devuelve sus IDs de nota, tipo de nota, etiquetas y un breve extracto de cada campo. Úsalo para obtener el noteId que update-card, update-cloze-card y delete-card necesitan.

El contenido de los campos se trunca y el número de resultados está limitado, así que estrecha la consulta si la nota que quieres no aparece — la respuesta siempre informa cuántas notas coincidieron en total.

Parámetros:
- query: Consulta de búsqueda de Anki, p. ej. deck:Spanish, tag:vocab, deck:Spanish tag:verbs

delete-card

Elimina notas permanentemente. Esto no se puede deshacer — no hay papelera para recuperarlas, y cada tarjeta generada a partir de una nota eliminada desaparece con ella.

Los IDs de nota deben listarse explícitamente; no hay eliminación por consulta. Usa find-cards primero para obtenerlos y comprobar que tienes las notas correctas. La respuesta informa qué IDs se eliminaron realmente y cuáles no existían, porque Anki informa éxito en ambos casos.

Parámetros:
- noteIds: IDs de las notas a eliminar, como máximo 50 por llamada
- confirm: Debe ser true

Recursos

Además de las herramientas anteriores, los mazos se exponen como un recurso legible.

anki://deck/`<name>`

Lee un mazo y devuelve cada nota en él — ID de nota, frontal, trasero y etiquetas. A diferencia de find-cards, el contenido se devuelve completo en lugar de truncado.

Ejemplos de Uso

Tarjeta básica solo con texto

"Create a flashcard in my Spanish deck with 'Hola' on the front and 'Hello' on the back"

Tarjeta con imágenes

"Create a flashcard about the Eiffel Tower with an image from https://example.com/eiffel.jpg on the front"

Tarjeta con audio

"Create a pronunciation card with audio from https://example.com/pronunciation.mp3"

Tarjeta con múltiples medios

"Create a card with images on both sides and audio on the back for studying animals"

Tarjeta de cloze con medios

"Create a cloze card: 'The capital of {{c1::France}} is {{c2::Paris}}' with an image of the Eiffel Tower"

Nota: Los archivos multimedia se descargan automáticamente desde URLs y se incrustan en las tarjetas. Asegúrate de que las URLs sean accesibles y apunten a archivos multimedia válidos. Una URL que no se pueda usar se informa en la respuesta de la herramienta; la nota se crea igualmente sin ese adjunto.

Ubicación de los medios: Los adjuntos se añaden al final del campo al que pertenecen, después de cualquier texto. No puedes posicionar una imagen en línea con HTML, porque el nombre del archivo se genera en el momento de la carga y no se conoce de antemano. El formato HTML y los adjuntos multimedia, por lo tanto, no se combinan: usa HTML para formatear tu texto, y los parámetros de medios para adjuntar archivos después.

Problema Conocido: Extra Trasero Faltante en Tarjetas de Cloze Antiguas

Las versiones anteriores escribían el valor de backExtra en un campo llamado Back. El tipo de nota integrado de Anki para Cloze no tiene ese campo — sus campos son Text y Back Extra — y AnkiConnect descarta silenciosamente los valores enviados a un campo que no existe.

Como resultado, las tarjetas cloze creadas antes de esta corrección no tienen contenido extra almacenado, aunque la tarjeta se reportó como creada exitosamente. El texto nunca se escribió en Anki, por lo que no se puede recuperar automáticamente; volver a ingresarlo en las tarjetas afectadas es la única solución.

Las tarjetas cloze creadas a partir de esta versión almacenan backExtra correctamente.

Desarrollo

Para modificar o ampliar el servidor:

Realiza cambios en src/index.ts
Reconstruye con npm run build
Depura con npx @modelcontextprotocol/inspector node build/index.js

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Agradecimientos

Construido con el Model Context Protocol SDK
Se integra con Anki a través de AnkiConnect

Clanki - Claude's Anki Integration

Documentación

Clanki - Claude's Anki Integration

Características

Requisitos previos

Instalación

Configuración

Claude Desktop

Claude Code

Codex

Configuración

Usar Anki en un idioma distinto del inglés

Conectarse a AnkiConnect en otro lugar

Herramientas Disponibles

create-deck

create-card

create-cloze-card

create-cards-bulk

create-cloze-cards-bulk

update-card

update-cloze-card

find-cards

delete-card

Recursos

anki://deck/<name>

Ejemplos de Uso

Tarjeta básica solo con texto

Tarjeta con imágenes

Tarjeta con audio

Tarjeta con múltiples medios

Tarjeta de cloze con medios

Problema Conocido: Extra Trasero Faltante en Tarjetas de Cloze Antiguas

Desarrollo

Licencia

Contribuciones

Agradecimientos

anki://deck/`<name>`