Anki MCP Server

Servidor MCP de Anki

Un servidor MCP (Protocolo de Contexto de Modelo) para Claude Desktop que se conecta a Anki a través de AnkiConnect y recupera tarjetas etiquetadas como leech.

Características

• Se conecta a Anki a través de la API de AnkiConnect
• Recupera tarjetas con etiquetas "leech"
• Añade etiquetas de revisión con fecha a las tarjetas
• Proporciona datos completos de tarjetas para que Claude los analice
• Puede utilizarse con Claude Desktop

Requisitos previos

• Anki instalado y en ejecución
• Complemento AnkiConnect instalado en Anki
• Node.js y npm

Instalación

1. Clona este repositorio:

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

2. Instala las dependencias:

   npm install
   

3. Compila el proyecto:

   npm run build
   

Configuración

El servidor se puede configurar mediante variables de entorno. Copia el archivo de ejemplo proporcionado para crear tu propia configuración:

cp .env.example .env

Luego edita el archivo .env para personalizar tu configuración:

Variable de entorno	Descripción	Valor predeterminado
ANKI_CONNECT_URL	La URL de la API de Anki Connect	http://localhost:8765
ANKI_CONNECT_VERSION	La versión de la API de Anki Connect a utilizar	6
ANKI_MOCK_MODE	Habilita el modo simulado para pruebas (true/false)	false

Si las variables de entorno no están configuradas, el servidor utilizará los valores predeterminados.

Cómo encontrar tu dirección IP local para AnkiConnect

Si la conexión a localhost no funciona, deberás utilizar la dirección IP local de tu computadora. Configura tu archivo .env con:

ANKI_CONNECT_URL=http://YOUR_LOCAL_IP:8765

Para encontrar tu dirección IP local:

• macOS: Abre Terminal y ejecuta ifconfig o ipconfig getifaddr en0 (para WiFi)
• Windows: Abre el Símbolo del sistema y ejecuta ipconfig
• Linux: Abre Terminal y ejecuta ip addr show o hostname -I

Busca direcciones IPv4 como 192.168.x.x o 10.x.x.x en la salida.

Configuración de pruebas

Para pruebas, se proporciona un archivo de configuración separado .env.test:

cp .env.example .env.test

Edita .env.test para establecer valores específicos de prueba:

ANKI_CONNECT_URL=http://localhost:8765
ANKI_CONNECT_VERSION=6
ANKI_MOCK_MODE=true

Para ejecutar en modo de prueba:

npm run start:test

Uso

1. Asegúrate de que Anki esté en ejecución con AnkiConnect instalado
2. Ejecuta el servidor MCP:

   npm start
   

Configuración de Claude Desktop

Para utilizar este servidor MCP con Claude Desktop:

1. Abre Claude Desktop

2. Edita el archivo de configuración de Claude Desktop ubicado en:

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

3. Añade la siguiente configuración a la sección mcpServers:

{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["path/to/anki-mcp-server/dist/index.js"]
    }
  }
}

Reemplaza "path/to/anki-mcp-server" con la ruta real donde clonaste este repositorio.

Uso de la herramienta MCP

Una vez configurado, puedes utilizar las siguientes herramientas en Claude:

Ejemplo de uso

Could you analyze my Anki leech cards and suggest ways to improve my study?

Claude utilizará el servidor MCP para recuperar tus tarjetas leech y analizarlas.

Herramientas disponibles

get_leech_cards

Recupera tarjetas etiquetadas como leech de Anki.

Parámetros:

• detailed (opcional, booleano, predeterminado: true): Si se deben devolver datos completos de tarjetas o solo los IDs
• count (opcional, número): Número de tarjetas aleatorias a devolver (predeterminado: todas las tarjetas)

tag_reviewed_cards

Añade una etiqueta "revisado" con fecha a las tarjetas especificadas. Esto te permite realizar un seguimiento de las tarjetas que has revisado con Claude.

Parámetros:

• card_ids (obligatorio, matriz de números): Matriz de IDs de tarjetas para etiquetar como revisadas
• custom_tag_prefix (opcional, cadena, predeterminado: "見直し"): Prefijo personalizado para la etiqueta

La etiqueta tendrá el formato 見直し::YYYYMMDD (o tu prefijo personalizado si se especifica).

Ejemplo de uso en Claude:

I've reviewed these cards, please tag them as reviewed: [1234567890, 1234567891]

Solución de problemas

• "No se pudo conectar a Anki" - Asegúrate de que Anki esté en ejecución y AnkiConnect esté instalado correctamente
• "No se encontraron tarjetas leech" - No tienes tarjetas etiquetadas como "leech" en Anki
• Problemas de conexión con localhost - Si no puedes conectarte usando localhost:
  1. Encuentra tu dirección IP local como se describe en la sección de Configuración
  2. Actualiza tu archivo .env para usar ANKI_CONNECT_URL=http://YOUR_LOCAL_IP:8765
  3. Asegúrate de que AnkiConnect esté configurado para permitir conexiones desde tu dirección IP
  4. Reinicia el servidor MCP después de realizar estos cambios
• La etiqueta no aparece - Asegúrate de proporcionar IDs de tarjetas válidos a la herramienta tag_reviewed_cards

Modo de prueba

Para pruebas sin afectar los datos reales de Anki, puedes utilizar el modo simulado:

1. Establece ANKI_MOCK_MODE=true en tu archivo .env o utiliza el archivo .env.test proporcionado
2. Ejecuta el servidor con npm run start:test

En modo simulado, el servidor simulará todas las operaciones de Anki sin conectarse realmente a Anki. Esto es útil para probar integraciones con Claude sin arriesgar cambios en los datos.

Desarrollo

Para ejecutar el servidor en modo de desarrollo con recarga automática:

npm run dev

Para desarrollo con modo simulado habilitado:

npm run dev:test

Licencia

MIT