AnkiMCP Server (Аддон)

Аддон для Anki, который предоставляет доступ к вашей коллекции для ИИ-ассистентов через Model Context Protocol (MCP).

Что это такое?

AnkiMCP Server запускает локальный MCP-сервер внутри Anki, позволяя ИИ-ассистентам, таким как Claude, взаимодействовать с вашей коллекцией карточек. Это открывает возможности для учебных сессий с ИИ, создания карточек и управления коллекцией.

Часть проекта ankimcp.ai.

Related MCP server: Anki MCP Server

Примечание при первом запуске

При первом запуске этот аддон загружает pydantic_core (~2 МБ) из PyPI. Это необходимо, так как pydantic_core содержит специфичные для платформы бинарные файлы (Windows/macOS/Linux), которые невозможно включить в один файл аддона.

Возможности

• Локальный HTTP-сервер — по умолчанию работает на http://127.0.0.1:3141/

• Протокол MCP — совместим с любым MCP-клиентом (Claude Desktop и др.)

• Автозапуск — сервер запускается автоматически при открытии Anki

• Поддержка туннелей — работает с Cloudflare Tunnel, ngrok и т.д.

• Кроссплатформенность — работает на macOS, Windows и Linux (x64 и ARM)

Установка

Из AnkiWeb (рекомендуется)

1. Откройте Anki и перейдите в Инструменты → Дополнения → Получить дополнения...

2. Введите код: 124672614

3. Перезапустите Anki

Из GitHub Releases

1. Скачайте anki_mcp_server.ankiaddon из Releases

2. Дважды щелкните для установки или используйте Инструменты → Дополнения → Установить из файла...

3. Перезапустите Anki

NixOS

С использованием flakes (рекомендуется)

Добавьте входные данные flake и используйте предварительно собранный пакет:

# 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 ])
    ];
  };
}

Без 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 ];
}

Использование

Сервер запускается автоматически при открытии Anki. Проверить статус можно через Инструменты → AnkiMCP Server Settings...

Подключение к Claude Desktop

Требуется установленный Node.js. Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

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

Примечание: Claude Desktop не поддерживает HTTP-серверы в своем JSON-конфиге напрямую — mcp-remote обеспечивает соединение через stdio.

Подключение к Claude Code

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

Конфигурация

Редактируется через Инструменты → Дополнения → AnkiMCP Server → Config в 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": []
}

Отключение инструментов

Скройте определенные инструменты или действия от ИИ-клиентов, чтобы уменьшить использование токенов:

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

• "tool_name" — отключает весь инструмент целиком

• "tool_name:action" — отключает конкретное действие внутри многофункционального инструмента

Отключенные инструменты полностью удаляются из схемы MCP — ИИ-клиенты их не видят. Опечатки в названиях инструментов/действий вызовут предупреждения в консоли.

Пользовательский путь

Установите http_path, чтобы обслуживать MCP-эндпоинт по пользовательскому пути. Полезно при публикации Anki через туннель (Cloudflare, ngrok), чтобы избежать полностью открытого эндпоинта:

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

Сервер будет доступен по адресу http://localhost:3141/my-secret-path/ вместо корня. Оставьте пустым для поведения по умолчанию.

Конфигурация CORS

Чтобы разрешить браузерным MCP-клиентам (например, веб-версии MCP Inspector) доступ, добавьте разрешенные источники:

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

Используйте ["*"], чтобы разрешить все источники (не рекомендуется для продакшена).

Настройка cors_expose_headers определяет, какие заголовки ответа могут читать браузеры. Значения по умолчанию (mcp-session-id, mcp-protocol-version) необходимы для работы протокола MCP Streamable HTTP в браузерах.

Безопасность медиафайлов

Спасибо Hideaki Takahashi (Колумбийский университет) за ответственное раскрытие уязвимости обхода пути к медиафайлам.

Инструмент store_media_file проверяет все входные данные для предотвращения атак типа path traversal и SSRF:

• Пути к файлам ограничены только медиафайлами (изображения, аудио, видео) через проверку MIME-типа

• URL-адреса должны использовать http:// или https:// и не могут указывать на частные/внутренние сети

• Имена файлов очищаются от последовательностей обхода пути

Дополнительная защита через конфигурацию:

{
  "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 — ограничить импорт файлов этим деревом каталогов (пусто = без ограничений)

• media_allowed_types — разрешить дополнительные MIME-типы помимо изображений/аудио/видео

• media_allowed_hosts — разрешить определенным хостам обходить блокировку частных сетей

Доступные инструменты

Основные инструменты

Инструменты FSRS

Инструменты GUI

Эти инструменты взаимодействуют с пользовательским интерфейсом Anki:

Ресурсы

Промпты

Требования

• Anki 25.07 или новее (поставляется с Python 3.13)

• Anki 25.02 и более ранние версии поставляются с Python 3.9, который не поддерживается — MCP SDK требует Python 3.10+ (#8)

Архитектура

Аддон запускает MCP-сервер в фоновом потоке с использованием HTTP-транспорта (FastMCP + uvicorn). Все операции Anki передаются в основной поток Qt через систему очередей, следуя той же проверенной схеме, что и AnkiConnect.

Подробности см. в Документации по разработке дополнений Anki.

Разработка

Запуск E2E-тестов

E2E-тесты запускаются против реального экземпляра Anki в Docker с использованием 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

Или используйте сокращения 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

E2E-тесты запускаются автоматически при пуше в любую ветку и при создании PR в main. См. .github/workflows/e2e.yml.

Лицензия

AGPL-3.0-or-later

Ссылки

• ankimcp.ai - Домашняя страница проекта

• MCP Protocol - Спецификация Model Context Protocol

• Anki Add-on Docs - Официальная документация по разработке дополнений Anki