Servidor AnkiMCP (Complemento)

Un complemento de Anki que expone tu colección a asistentes de IA mediante el Protocolo de Contexto de Modelo (MCP).

¿Qué es esto?

El servidor AnkiMCP ejecuta un servidor MCP local dentro de Anki, permitiendo que asistentes de IA como Claude interactúen con tu colección de tarjetas. Esto permite sesiones de estudio potenciadas por IA, creación de tarjetas y gestión de la colección.

Parte del proyecto ankimcp.ai.

Related MCP server: Anki MCP Server

Nota sobre la primera ejecución

En la primera ejecución, este complemento descarga pydantic_core (~2MB) desde PyPI. Esto es necesario porque pydantic_core contiene binarios específicos de la plataforma (Windows/macOS/Linux) que no pueden incluirse en un único archivo de complemento.

Características

• Servidor HTTP local - Se ejecuta en http://127.0.0.1:3141/ por defecto

• Protocolo MCP - Compatible con cualquier cliente MCP (Claude Desktop, etc.)

• Inicio automático - El servidor se inicia automáticamente al abrir Anki

• Compatible con túneles - Funciona con Cloudflare Tunnel, ngrok, etc.

• Multiplataforma - Funciona en macOS, Windows y Linux (x64 y ARM)

Instalación

Desde AnkiWeb (recomendado)

1. Abre Anki y ve a Herramientas → Complementos → Obtener complementos...

2. Introduce el código: 124672614

3. Reinicia Anki

Desde GitHub Releases

1. Descarga anki_mcp_server.ankiaddon desde Releases

2. Haz doble clic para instalar, o usa Herramientas → Complementos → Instalar desde archivo...

3. Reinicia Anki

NixOS

Con flakes (recomendado)

Añade la entrada flake y usa el paquete precompilado:

# flake.nix
{
  inputs.anki-mcp.url = "github:ankimcp/anki-mcp-server-addon";

  outputs = { nixpkgs, anki-mcp, ... }: {
    # Option A: Standalone — Anki with the addon pre-installed
    environment.systemPackages = [
      anki-mcp.packages.${system}.default
    ];

    # Option B: Composable with other addons via overlay
    nixpkgs.overlays = [ anki-mcp.overlays.default ];
    environment.systemPackages = [
      (pkgs.anki.withAddons [ pkgs.ankiAddons.anki-mcp-server ])
    ];
  };
}

Sin flakes

# configuration.nix
{ pkgs, ... }:
let
  python3 = pkgs.python3;

  ankiMcpPythonDeps = python3.withPackages (ps: with ps; [
    mcp pydantic pydantic-settings starlette uvicorn anyio httpx websockets
  ]);

  anki-mcp-server = pkgs.anki-utils.buildAnkiAddon (finalAttrs: {
    pname = "anki-mcp-server";
    version = "0.13.0";
    src = pkgs.fetchFromGitHub {
      owner = "ankimcp";
      repo = "anki-mcp-server-addon";
      rev = "v${finalAttrs.version}";
      hash = ""; # nix will tell you the correct hash on first build
    };
    sourceRoot = "${finalAttrs.src.name}/anki_mcp_server";
  });

  ankiWithMcp = pkgs.anki.withAddons [ anki-mcp-server ];

  ankiWrapped = pkgs.symlinkJoin {
    name = "anki-with-mcp";
    paths = [ ankiWithMcp ];
    nativeBuildInputs = [ pkgs.makeWrapper ];
    postBuild = ''
      wrapProgram $out/bin/anki \
        --prefix PYTHONPATH ':' "${ankiMcpPythonDeps}/${python3.sitePackages}"
    '';
  };
in
{
  environment.systemPackages = [ ankiWrapped ];
}

Uso

El servidor se inicia automáticamente al abrir Anki. Comprueba el estado a través de Herramientas → Configuración del servidor AnkiMCP...

Conectar con Claude Desktop

Requiere tener instalado Node.js. Añádelo a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3141"]
    }
  }
}

Nota: Claude Desktop no admite de forma nativa servidores HTTP en su configuración JSON — mcp-remote puentea la conexión mediante stdio.

Conectar con Claude Code

claude mcp add anki --transport http http://127.0.0.1:3141/

Configuración

Edita a través de Herramientas → Complementos → AnkiMCP Server → Configuración de Anki:

{
  "mode": "http",
  "http_port": 3141,
  "http_host": "127.0.0.1",
  "http_path": "",
  "cors_origins": [],
  "cors_expose_headers": ["mcp-session-id", "mcp-protocol-version"],
  "auto_connect_on_startup": true,
  "disabled_tools": [],
  "media_import_dir": "",
  "media_allowed_types": [],
  "media_allowed_hosts": []
}

Deshabilitar herramientas

Oculta herramientas o acciones específicas de los clientes de IA para reducir el uso de tokens:

{
  "disabled_tools": [
    "sync",
    "card_management:bury",
    "card_management:unbury"
  ]
}

• "tool_name" — deshabilita la herramienta completa

• "tool_name:action" — deshabilita una acción específica dentro de una herramienta multiacción

Las herramientas deshabilitadas se eliminan por completo del esquema MCP; los clientes de IA nunca las ven. Los errores tipográficos en los nombres de herramientas/acciones producirán advertencias en la consola.

Ruta personalizada

Establece http_path para servir el endpoint MCP bajo una ruta personalizada. Útil cuando se expone Anki a través de un túnel (Cloudflare, ngrok) para evitar un endpoint totalmente abierto:

{
  "http_path": "my-secret-path"
}

El servidor será accesible en http://localhost:3141/mi-ruta-secreta/ en lugar de la raíz. Déjalo vacío para el comportamiento por defecto.

Configuración de CORS

Para permitir clientes MCP basados en navegador (como el Inspector MCP alojado en web), añade orígenes permitidos:

{
  "cors_origins": ["https://inspector.example.com", "http://localhost:5173"]
}

Usa ["*"] para permitir todos los orígenes (no recomendado para producción).

El ajuste cors_expose_headers controla qué cabeceras de respuesta pueden leer los navegadores. Los valores por defecto (mcp-session-id, mcp-protocol-version) son necesarios para que el protocolo HTTP Streamable de MCP funcione en navegadores.

Seguridad de medios

Gracias a Hideaki Takahashi (Universidad de Columbia) por revelar responsablemente la vulnerabilidad de recorrido de ruta de medios.

La herramienta store_media_file valida todas las entradas para prevenir ataques de recorrido de ruta y SSRF:

• Las rutas de archivo están restringidas solo a archivos multimedia (imágenes, audio, vídeo) mediante la comprobación del tipo MIME

• Las URLs deben usar http:// o https:// y no pueden apuntar a redes privadas/internas

• Los nombres de archivo se desinfectan para eliminar secuencias de recorrido de ruta

Endurecimiento opcional mediante configuración:

{
  "media_import_dir": "/Users/me/anki-media",
  "media_allowed_types": ["application/pdf"],
  "media_allowed_hosts": ["192.168.1.50", "my-nas.local"]
}

• media_import_dir — restringe las importaciones de rutas de archivo a este árbol de directorios (vacío = sin restricción)

• media_allowed_types — permite tipos MIME adicionales más allá de imagen/audio/vídeo

• media_allowed_hosts — permite que hosts específicos omitan el bloqueo de red privada

Herramientas disponibles

Herramientas esenciales

Herramientas FSRS

Herramientas GUI

Estas herramientas interactúan con la interfaz de usuario de Anki:

Recursos

Prompts

Requisitos

• Anki 25.07 o posterior (incluye Python 3.13)

• Anki 25.02 y anteriores incluyen Python 3.9, que no es compatible — el SDK de MCP requiere Python 3.10+ (#8)

Arquitectura

El complemento ejecuta un servidor MCP en un hilo en segundo plano con transporte HTTP (FastMCP + uvicorn). Todas las operaciones de Anki se puentean al hilo principal de Qt mediante un sistema de colas, siguiendo el mismo patrón probado que AnkiConnect.

Para más detalles, consulta la Documentación de desarrollo de complementos de Anki.

Desarrollo

Ejecución de pruebas E2E

Las pruebas E2E se ejecutan contra una instancia real de Anki en Docker usando headless-anki.

# Install test dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

# Build the addon
./package.sh

# Start Anki container
cd .docker && docker compose up -d && cd ..

# Run tests (waits for server automatically)
pytest tests/e2e/ -v

# Stop container
cd .docker && docker compose down

O usa los atajos de Makefile:

make e2e        # Build, start container, run tests, stop
make e2e-up     # Just start container
make e2e-test   # Just run tests
make e2e-down   # Just stop container

CI

Las pruebas E2E se ejecutan automáticamente al hacer push a cualquier rama y en PRs a main. Consulta .github/workflows/e2e.yml.

Licencia

AGPL-3.0-or-later

Enlaces

• ankimcp.ai - Página principal del proyecto

• Protocolo MCP - Especificación del Protocolo de Contexto de Modelo

• Documentación de complementos de Anki - Documentación oficial de desarrollo de complementos de Anki