Anki MCP

официальный

MCP-сервер, который позволяет AI-ассистентам взаимодействовать с Anki — приложением для интервальных повторений флеш-карт.

GitHub

408

Что можно делать с Anki MCP?

Интерактивный просмотр карточек к повторению — Попросите ассистента получить карточки к повторению с помощью get_due_cards, показать их через present_card и записать вашу оценку с помощью rate_card.
Создание и настройка пользовательских типов заметок — Создайте новый тип заметок с определёнными полями, шаблонами карточек и CSS, используя createModel, updateModelStyling и updateModelTemplates.
Пакетное добавление карточек из списка — Предоставьте набор заметок, и ассистент создаст их все сразу с помощью addNotes, используя одну и ту же колоду и модель.
Поиск и обновление существующих заметок — Найдите заметки по колоде, тегу или статусу повторения с помощью findNotes, затем измените их поля или теги, используя updateNoteFields, addTags или removeTags.
Управление медиафайлами в коллекции — Загрузите изображения или аудио из локального пути с помощью storeMediaFile, получите список сохранённых файлов через getMediaFilesNames или удалите неиспользуемые медиафайлы.
Открытие графического интерфейса Anki для ручного редактирования — Используйте guiBrowse для открытия браузера карточек, guiAddCards для предварительного заполнения диалога добавления карточек или guiEditNote для редактирования конкретной заметки.

Документация

Anki MCP Server

Бесшовная интеграция Anki с AI-ассистентами через Model Context Protocol

Бета — Проект находится в активной разработке. API и функции могут изменяться.

Сервер Model Context Protocol (MCP), позволяющий AI-ассистентам взаимодействовать с Anki — приложением для интервальных повторений с флеш-карточками.

Преобразите свой опыт работы с Anki с помощью взаимодействия на естественном языке — как с личным репетитором. AI-ассистент не просто показывает вопросы и ответы; он может объяснять концепции, делать процесс обучения более увлекательным и человечным, предоставлять контекст и адаптироваться к вашему стилю обучения. Он может создавать и редактировать заметки на лету, превращая учебные сессии в динамичные беседы. Скоро появятся новые функции!

Примеры и руководства

Подробные руководства, реальные примеры и пошаговые инструкции по использованию этого MCP-сервера с Claude Desktop можно найти здесь:

ankimcp.ai — Полная документация с практическими примерами и вариантами использования

См. docs/ для получения дополнительной документации, включая руководство по настройке рецензента и образец колоды Anki.

Примеры использования

Три типичных запроса, демонстрирующих потоки инструментов, которые обеспечивает этот сервер:

«Помоги мне повторить мою колоду испанского». — Ассистент синхронизируется с AnkiWeb (sync), извлекает карточки для повторения (get_due_cards с фильтром по колоде), показывает каждую карточку (present_card) и записывает вашу оценку (rate_card). Естественная учебная беседа с индивидуальными объяснениями.
«Создай 10 карточек арабской лексики со стилями RTL». — Ассистент выводит список типов заметок (modelNames), при необходимости создает пользовательскую модель RTL (createModel + updateModelStyling для CSS с направлением справа налево), затем пакетно создает карточки (addNotes).
«Импортируй это изображение из моей папки Downloads на лицевую сторону выбранной заметки». — Ассистент загружает локальный файл (storeMediaFile с путем к файлу), считывает текущую выбранную заметку из браузера (guiSelectedNotes + notesInfo) и обновляет лицевое поле тегом <img> (updateNoteFields).

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

Сервер предоставляет 42 инструмента MCP — 31 основной инструмент для повседневных операций Anki и 11 инструментов GUI, управляющих интерфейсом рабочего стола Anki для редактирования и создания заметок.

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

Повторение и изучение

sync — Синхронизация с AnkiWeb для получения последних данных и отправки изменений
get_due_cards — Получение карточек, подлежащих повторению, с возможной фильтрацией по колоде
get_cards — Получение карточек с гибкой фильтрацией по состоянию (due, new, learning, suspended, buried) и колоде
present_card — Показ карточки для повторения с ее вопросом/лицевой стороной
rate_card — Оценка успеваемости по карточке (Again, Hard, Good, Easy) и планирование следующего повторения

Примечание: Содержимое front/back карточки отображается для каждой карточки из ее собственного шаблона (как это показывает Anki), поэтому перевернутые карточки и карточки с клоузом отображаются в правильном направлении. Статический текст, добавленный вашими шаблонами карточек, также появляется в выводе.

Управление колодами

listDecks — Список всех колод, опционально со статистикой количества карточек по колодам
deckStats — Получение подробной статистики по одной колоде (количество, распределение легкости/интервалов)
createDeck — Создание новой пустой колоды (поддерживает Parent::Child, максимум 2 уровня)
changeDeck — Перемещение карточек в другую колоду (создается, если не существует)

Управление заметками

addNote — Создание одной заметки с указанными полями и тегами
addNotes — Пакетное создание до 100 заметок с общей колодой и моделью (поддерживается частичный успех)
findNotes — Поиск заметок с использованием синтаксиса запросов Anki (deck:, tag:, is:due и т.д.)
notesInfo — Получение подробной информации о заметках (поля, теги, стили CSS)
updateNoteFields — Обновление полей существующей заметки (с учетом CSS, поддерживает HTML-контент)
deleteNotes — Удаление заметок и всех связанных карточек (деструктивное действие, требует подтверждения)

Управление тегами

getTags — Получение всех тегов в коллекции (используйте сначала, чтобы избежать дублирования)
addTags — Добавление тегов, разделенных пробелами, к указанным заметкам
removeTags — Удаление тегов, разделенных пробелами, из указанных заметок
replaceTags — Переименование тега в указанных заметках
clearUnusedTags — Удаление потерянных тегов, не используемых ни в одной заметке (деструктивное действие)

Управление медиафайлами

getMediaFilesNames — Список медиафайлов в collection.media, опционально с фильтрацией по шаблону
retrieveMediaFile — Загрузка медиафайла в виде содержимого base64
storeMediaFile — Загрузка медиафайла из данных base64, абсолютного пути к файлу или URL
deleteMediaFile — Удаление медиафайла из collection.media (деструктивное действие)

💡 Лучшая практика для изображений:

✅ Используйте пути к файлам (например, /Users/you/image.png) — Быстро и эффективно
✅ Используйте URL (например, https://example.com/image.jpg) — Прямая загрузка
❌ Избегайте base64 — Чрезвычайно медленно и неэффективно по токенам

Просто скажите Claude, где находится изображение, и он автоматически загрузит его, используя наиболее эффективный метод.

Управление моделями/шаблонами

modelNames — Список всех доступных типов заметок/моделей
modelFieldNames — Получение имен полей для конкретного типа заметки
modelStyling — Получение информации о стилях CSS для типа заметки
modelTemplates — Получение шаблонов карточек (HTML лицевой и обратной стороны) для типа заметки
createModel — Создание нового типа заметки с пользовательскими полями, шаблонами карточек и CSS (например, модели RTL)
updateModelStyling — Обновление стилей CSS для существующего типа заметки (применяется ко всем его карточкам)
updateModelTemplates — Обновление шаблонов карточек (HTML лицевой и обратной стороны) для существующего типа заметки (применяется ко всем его карточкам)
addModelField — Добавление нового поля в существующий тип заметки (добавляется в конец или вставляется в определенную позицию)
removeModelField — Удаление поля из существующего типа заметки (удаляет его содержимое из всех заметок; требует явного подтверждения)
renameModelField — Переименование поля в существующем типе заметки (шаблоны карточек, ссылающиеся на старое имя, необходимо обновить отдельно)
repositionModelField — Изменение позиции поля в существующем типе заметки

Статистика

collection_stats — Агрегированная статистика по всем колодам с разбивкой по колодам
review_stats — Анализ истории повторений (временные закономерности, показатели запоминания, учебные серии)

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

Инструменты, управляющие интерфейсом рабочего стола Anki. Предназначены для редактирования/создания заметок и управления колодами, не для сеансов повторения.

guiBrowse — Открыть обозреватель карточек и выполнить поиск
guiSelectCard — Выбрать конкретную карточку в обозревателе карточек
guiSelectedNotes — Получить ID заметок, выбранных в данный момент в обозревателе карточек
guiAddCards — Открыть диалог добавления карточек с предустановленными деталями заметки
guiEditNote — Открыть редактор заметок для конкретной заметки
guiDeckOverview — Открыть диалог обзора колоды для конкретной колоды
guiDeckBrowser — Открыть диалог обозревателя колод
guiCurrentCard — Получить информацию о текущей карточке в режиме повторения
guiShowQuestion — Показать лицевую сторону текущей карточки
guiShowAnswer — Показать обратную сторону текущей карточки
guiUndo — Отменить последнее действие в Anki

Предварительные требования

Anki с установленным плагином AnkiConnect
Node.js 22.12.0+

Установка

Существует несколько способов установить сервер на ваш компьютер. После установки перейдите к разделу Подключение AI-клиента, чтобы подключить его к вашему AI-ассистенту — локально или удаленно.

npm (глобально или npx)

Универсальный способ установки сервера, подходящий для любого MCP-клиента, который запускает его напрямую.

Установите глобально для клиентов, выполняющих команду ankimcp:

npm install -g @ankimcp/anki-mcp-server

Или запускайте по требованию без установки:

npx @ankimcp/anki-mcp-server

Пакет MCPB (рекомендуется для Claude Desktop)

Самый простой способ установить этот MCP-сервер для Claude Desktop:

Загрузите последний пакет .mcpb со страницы Releases
В Claude Desktop установите расширение:
- Способ 1: Перейдите в Settings → Extensions, затем перетащите файл .mcpb
- Способ 2: Перейдите в Settings → Developer → Extensions → Install Extension, затем выберите файл .mcpb
При необходимости настройте URL AnkiConnect (по умолчанию http://localhost:8765)
Перезапустите Claude Desktop

Вот и всё! Пакет включает всё необходимое для локального запуска сервера.

Для рецензентов Anthropic MCP Directory: пошаговое руководство от нуля до интеграции с предварительно заполненной образцовой колодой находится в docs/reviewer-setup.md.

Установка из исходников (для разработки)

Для разработки или продвинутого использования:

npm install
npm run build

Подключение AI-клиента

Существует два способа, с помощью которых AI-ассистент может подключиться к этому серверу, в зависимости от того, где работает ассистент:

Локально — сервер работает на той же машине, что и AI-клиент (Claude Desktop, Cursor, Cline, Zed или локальный сеанс браузера). Используйте STDIO для настольных MCP-клиентов, HTTP для локальных веб-инструментов.
Удаленно — размещенный/удаленный AI (например, ChatGPT или Claude.ai в облаке) должен подключаться к Anki, работающему на вашей локальной машине. Используйте управляемый туннель (✅ рекомендуется — с аутентификацией) или, как более легкую альтернативу без аутентификации, ngrok.

Локально

Сервер работает на том же компьютере, что и ваш AI-клиент, и взаимодействует с AnkiConnect через localhost.

STDIO (основная локальная интеграция)

STDIO — это стандартный транспорт для локальных настольных MCP-клиентов — Claude Desktop, Cursor IDE, Cline, Zed Editor и других. Клиент запускает сервер как подпроцесс и обменивается данными через стандартный ввод/вывод.

Поддерживаемые клиенты:

Claude Desktop
Cursor IDE — редактор кода на базе AI
Cline — расширение VS Code для помощи AI
Zed Editor — быстрый, современный редактор кода
Другие MCP-клиенты, поддерживающие транспорт STDIO

Для Claude Desktop пакет MCPB — самый простой путь. Для других клиентов настройте пакет npm с флагом --stdio.

Конфигурация — выберите один способ:

Способ 1: Использование npx (рекомендуется — установка не требуется)

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Способ 2: Использование глобальной установки

Сначала установите глобально:

npm install -g @ankimcp/anki-mcp-server

Затем настройте:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Расположение файлов конфигурации:

Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) или %USERPROFILE%\.cursor\mcp.json (Windows)
Cline: Доступно через пользовательский интерфейс настроек в VS Code
Zed Editor: Установите как расширение MCP через магазин расширений

Для получения информации о функциях, специфичных для клиента, и устранения неполадок обратитесь к документации вашего MCP-клиента. См. также Подключение к Claude Desktop для конфигурации, указывающей непосредственно на собранный dist/main-stdio.js.

HTTP (локальный веб-интерфейс AI)

Режим HTTP запускает сервер как локальный веб-сервер, использующий протокол MCP Streamable HTTP. Это транспорт, с которым взаимодействует веб-инструмент AI, когда он направлен на вашу машину, и это также то, что удаленные варианты предоставляют внешнему миру. Сам по себе режим HTTP привязывается только к localhost.

Привязка за пределами localhost? Если вы передаете --host 0.0.0.0 (или работаете за обратным прокси/публичным доменом), сервер по умолчанию принимает только заголовки loopback Host для защиты от DNS-ребендинга — установите ALLOWED_HOSTS на имя(имена) хоста, используемые клиентами. См. Конфигурация режима HTTP.

Настройка — выберите один способ:

Способ 1: Использование npx (рекомендуется — установка не требуется)

# Quick start
npx @ankimcp/anki-mcp-server

# With custom options
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765

Метод 2: Использование глобальной установки

# Install once
npm install -g @ankimcp/anki-mcp-server

# Run the server
ankimcp

# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765

Метод 3: Установка из исходников (для разработки)

npm install
npm run build
npm run start:prod:http

Чтобы локальный HTTP-сервер был доступен облачному ИИ, используйте один из вариантов Удалённого доступа ниже.

Удалённый доступ

Размещённый/удалённый ИИ (например, ChatGPT или Claude.ai, работающие в облаке) не может напрямую подключиться к localhost. Эти варианты открывают ваш локальный Anki в интернет, чтобы удалённый ассистент мог с ним взаимодействовать.

Туннель (✅ Рекомендуется)

Рекомендуемый путь для удалённого доступа — с аутентификацией и безопасностью. В отличие от открытого публичного порта, режим туннеля требует входа в систему (поток устройства OAuth 2.0), поэтому конечная точка не открыта для всех, кто угадает URL.

Режим туннеля позволяет веб-ИИ-ассистентам достигать вашего локального Anki без запуска собственного туннеля. Сервер подключается к управляемому сервису туннелей AnkiMCP (wss://tunnel.ankimcp.ai) через WebSocket и получает публичный URL. Аутентификация встроена — не требуется аккаунт ngrok или отдельный процесс туннеля, и вы входите в систему один раз.

Вход в систему (поток устройства OAuth):

Режим туннеля использует OAuth 2.0 Device Authorization Grant. При входе автоматически открывается браузер на странице подтверждения с уже встроенным в URL кодом — ничего вводить не нужно, просто подтвердите. (Если браузер не может открыться, терминал выводит URL для верификации и код для ручного ввода в качестве запасного варианта.) При успехе учётные данные сохраняются в ~/.ankimcp/credentials.json (права доступа к файлу 0600).

# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
ankimcp --login
npx @ankimcp/anki-mcp-server --login

# Clear saved credentials
ankimcp --logout

Запуск туннеля:

# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
ankimcp --tunnel
npx @ankimcp/anki-mcp-server --tunnel

# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
ankimcp --tunnel wss://my-tunnel.example.com

Если учётные данные отсутствуют, --tunnel автоматически сначала запускает процесс входа, а затем продолжает работу с туннелем. Этот автовход требует интерактивного терминала — когда stdout не является TTY (systemd, headless Docker, CI), сервер быстро завершает работу с ошибкой и просит сначала запустить ankimcp --login. После подключения выводится публичный URL туннеля; нажмите Ctrl+C для отключения. Поделитесь этим URL со своим ИИ-ассистентом.

Переменные окружения для режима туннеля:

Переменная	Описание	По умолчанию
`TUNNEL_SERVER_URL`	WebSocket URL сервера туннеля (значение флага `--tunnel`/`--login` переопределяет это)	`wss://tunnel.ankimcp.ai`
`TUNNEL_AUTH_CLIENT_ID`	Идентификатор клиента OAuth для потока устройства. Для продвинутых пользователей — нужен только при указании на собственный сервис туннеля/аутентификации.	(встроенный)

Конечные точки аутентификации потока устройства (/auth/device, /auth/token) извлекаются из TUNNEL_SERVER_URL, поэтому указание --tunnel (или TUNNEL_SERVER_URL) на другой хост также переносит аутентификацию на этот хост.

Как это работает: Режим туннеля запускает MCP-сервер внутри процесса за внутрипроцессным транспортом (McpModule запускается без встроенного транспорта). TunnelMcpService подключает этот внутрипроцессный транспорт к MCP-серверу, а TunnelClient соединяет его с удалённым сервисом туннеля через WebSocket — передавая MCP-запросы внутрь и ответы наружу. AnkiConnect по-прежнему доступен только на вашей локальной машине.

ngrok (неаутентифицированная альтернатива)

Если вы предпочитаете открыть локальный HTTP-режим публично без аккаунта в управляемом туннеле, встроенный флаг --ngrok запускает подпроцесс ngrok (src/services/ngrok.service.ts) и выводит публичный URL в стартовом баннере:

# One-time ngrok setup, then:
ankimcp --ngrok

Этот путь неаутентифицирован — любой, у кого есть URL, может получить доступ к вашему Anki, поэтому он менее безопасен, чем Туннель. Предпочитайте Туннель, если у вас нет особых причин управлять собственной конечной точкой ngrok. (Требуется глобальная установка ngrok и authtoken.)

Флаг --ngrok запускает ngrok с --host-header=rewrite, поэтому ngrok перезаписывает вышестоящий Host на localhost перед пересылкой. Это сохраняет запросы в пределах белого списка хостов loopback (см. защиту от DNS-ребандинга) без необходимости добавлять публичный домен *.ngrok в ALLOWED_HOSTS. Если вы вместо этого запускаете ngrok вручную, используйте тот же флаг — ngrok http --host-header=rewrite 3000 — иначе ngrok пересылает публичное имя хоста ngrok как Host, и сервер отклоняет его с ошибкой 403.

Параметры CLI (все режимы)

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -p, --port <port>              Port to listen on (HTTP mode, default: 3000)
  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks all write operations)
  --help                         Show help message

Usage with npx (no installation needed):
  npx @ankimcp/anki-mcp-server                        # HTTP mode
  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
  npx @ankimcp/anki-mcp-server --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

Usage with global installation:
  npm install -g @ankimcp/anki-mcp-server             # Install once
  ankimcp                                             # HTTP mode
  ankimcp --port 8080                                 # Custom port
  ankimcp --stdio                                     # STDIO mode
  ankimcp --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

Режим только для чтения (все режимы)

Флаг --read-only предотвращает любые изменения в вашей коллекции Anki. При включении:

Все операции чтения работают нормально (просмотр колод, карточек, поиск заметок)
Операции повторения разрешены (sync, answerCards, suspend/unsuspend)
Изменения контента заблокированы (addNote, deleteNotes, createDeck, updateNoteFields и т.д.)
Полезно для безопасного изучения данных Anki без риска случайных изменений

# HTTP mode with read-only
ankimcp --read-only

# STDIO mode with read-only
ankimcp --stdio --read-only

# Can combine with other flags
ankimcp --ngrok --read-only

Вы также можете включить режим только для чтения через переменную окружения:

READ_ONLY=true ankimcp

Или в конфигурации MCP-клиента:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Подключение к Claude Desktop (Локальный режим)

Вы можете настроить сервер в Claude Desktop одним из способов:

Перейдя: Настройки → Разработчик → Редактировать конфигурацию
Или вручную отредактировав файл конфигурации

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

Добавьте следующее в конфигурацию Claude Desktop:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Замените /path/to/anki-mcp-server на фактический путь к вашему проекту.

Расположение файлов конфигурации

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

Для получения дополнительной информации см. официальную документацию MCP.

Переменные окружения (Необязательно)

Переменная	Описание	По умолчанию
`ANKI_CONNECT_URL`	URL AnkiConnect	`http://localhost:8765`
`ANKI_CONNECT_API_VERSION`	Версия API	`6`
`ANKI_CONNECT_API_KEY`	Ключ API, если настроен в AnkiConnect	-
`ANKI_CONNECT_TIMEOUT`	Тайм-аут запроса в мс	`5000`
`READ_ONLY`	Включить режим только для чтения (`true` или `1`)	`false`
`ALLOWED_HOSTS`	HTTP-режим: дополнительные значения заголовка `Host` для принятия помимо loopback (имена хостов через запятую). Требуется при привязке к LAN/публичному адресу или работе за обратным прокси. См. Конфигурация HTTP-режима.	только loopback
`ALLOWED_ORIGINS`	HTTP-режим: разделённый запятыми белый список шаблонов браузерных `Origin`/`Referer` (поддерживаются подстановочные знаки, например, `https://*.ngrok.io`).	`http://localhost:,http://127.0.0.1:,https://localhost:,https://127.0.0.1:`
`TUNNEL_SERVER_URL`	WebSocket URL сервера туннеля (только режим туннеля)	`wss://tunnel.ankimcp.ai`
`MEDIA_ALLOWED_TYPES`	Дополнительные MIME-типы, разрешённые для импорта путей к файлам (через запятую, например, `application/pdf`)	-
`MEDIA_IMPORT_DIR`	Ограничить импорт путей к файлам этой директорией	-
`MEDIA_ALLOWED_HOSTS`	Разрешить определённые хосты частных сетей для импорта URL (через запятую, например, `192.168.1.50,my-nas`)	-

Примеры использования

Поиск и обновление заметок

# Search for notes in a specific deck
findNotes(query: "deck:Spanish")

# Get detailed information about notes
notesInfo(notes: [1234567890, 1234567891])

# Update a note's fields (HTML content supported)
updateNoteFields(note: {
  id: 1234567890,
  fields: {
    "Front": "<b>¿Cómo estás?</b>",
    "Back": "How are you?"
  }
})

# Delete notes (requires confirmation)
deleteNotes(notes: [1234567890], confirmDeletion: true)

Примеры синтаксиса запросов Anki

Инструмент findNotes поддерживает мощный синтаксис запросов Anki:

"deck:DeckName" - Все заметки в определённой колоде
"tag:important" - Заметки с тегом "important"
"is:due" - Карточки, ожидающие повторения
"is:new" - Новые карточки, которые ещё не изучались
"added:7" - Заметки, добавленные за последние 7 дней
"front:hello" - Заметки с "hello" в поле front
"flag:1" - Заметки с красным флагом
"prop:due<=2" - Карточки, ожидающие повторения в течение 2 дней
"deck:Spanish tag:verb" - Заметки колоды Spanish с тегом verb (И)
"deck:Spanish OR deck:French" - Заметки из любой из колод

Важные замечания

Обработка CSS и HTML

Инструмент notesInfo возвращает информацию о стилях CSS для надлежащего учёта при рендеринге
Инструмент updateNoteFields поддерживает HTML-контент в полях и сохраняет стили CSS
Каждая модель заметок имеет свои собственные стили CSS - используйте modelStyling для получения CSS, специфичного для модели

Предупреждение об обновлении

⚠️ ВАЖНО: При использовании updateNoteFields НЕ просматривайте заметку в браузере Anki во время обновления, иначе поля не обновятся должным образом. Закройте браузер или переключитесь на другую заметку перед обновлением. См. Известные проблемы для получения дополнительной информации.

Безопасность удаления

Инструмент deleteNotes требует явного подтверждения (confirmDeletion: true) для предотвращения случайных удалений. Удаление заметки безвозвратно удаляет ВСЕ связанные карточки.

Безопасность

Проверка пути к медиафайлам и URL

Инструменты для работы с медиа (storeMediaFile, retrieveMediaFile, deleteMediaFile) и поля audio/picture updateNoteFields включают проверку безопасности для предотвращения злоупотреблений через инъекцию подсказок:

Импорт путей к файлам ограничен только типами медиафайлов (изображения, аудио, видео). Не-медиафайлы (например, ключи SSH, учётные данные, конфигурации оболочки) отклоняются на основе MIME-типа. Настройте MEDIA_ALLOWED_TYPES для разрешения дополнительных типов файлов или MEDIA_IMPORT_DIR для ограничения импорта определённой директорией.
Импорт URL проверяется на предмет SSRF-атак. Запросы к частным сетям (10.x, 172.16.x, 192.168.x), loopback (127.x), link-local (169.254.x) и не-HTTP(S) схемам блокируются. Настройте MEDIA_ALLOWED_HOSTS для разрешения определённых хостов частных сетей.
Имена файлов очищаются для предотвращения обхода пути (например, последовательности ../../ удаляются).

Эти меры защиты применяются к storeMediaFile, retrieveMediaFile, deleteMediaFile и полям audio/picture updateNoteFields.

Уязвимость обхода пути обнаружена Hideaki Takahashi.

Защита от DNS-ребандинга (HTTP-транспорт)

При работе в HTTP-режиме сервер проверяет заголовок Host в каждом запросе. По умолчанию принимаются только хосты loopback (localhost, 127.0.0.1, ::1), независимо от порта. Host является запрещённым для браузера заголовком, поэтому вредоносная веб-страница не может его подделать — это закрывает путь DNS-ребандинга, когда перенаправленная страница достигает локального сервера с поддельным Host и без Origin, и получает доступ к инструментам MCP. Запрещённый Host отклоняется с ошибкой 403.

Если вы привязываетесь к 0.0.0.0, работаете за обратным прокси или открываете домен публичного туннеля, установите ALLOWED_HOSTS (имена хостов через запятую), чтобы разрешить эти хосты. При туннелировании с ngrok сервер использует --host-header=rewrite, поэтому вышестоящий сервер по-прежнему видит loopback Host. См. Конфигурация HTTP-режима для полного списка опций.

Уязвимость DNS-ребандинга обнаружена avishaigo-commits и yotampe-pluto.

Политика конфиденциальности

Этот MCP-сервер работает локально на вашем компьютере и не собирает телеметрию, аналитику или данные об использовании.

Полная политика: https://ankimcp.ai/privacy/

Сбор данных: Сервер ничего не собирает. Он проксирует запросы между вашим ИИ-ассистентом и вашим локальным плагином AnkiConnect.
Использование / хранение: Никакого хранения на стороне сервера. Все данные карточек остаются в вашей установке Anki на вашем собственном устройстве.
Передача третьим лицам: Отсутствует. Сервер взаимодействует только с URL AnkiConnect, который вы настраиваете (по умолчанию: localhost). Если вы включаете встроенную синхронизацию AnkiWeb в Anki, это происходит напрямую между вашей установкой Anki и AnkiWeb — вне компетенции этого сервера.
Хранение данных: Неприменимо — никакие данные не сохраняются на стороне сервера.
Контакт: support@ankimcp.ai

Известные проблемы

Для получения полного списка известных проблем и ограничений посетите нашу документацию:

Документация по известным проблемам

Критические ограничения

Сбой обновления заметок при просмотре в браузере

⚠️ ВАЖНО: При обновлении заметок с помощью updateNoteFields обновление может молча завершиться ошибкой, если заметка в данный момент просматривается в окне браузера Anki. Это ограничение вышестоящего AnkiConnect.

Обходной путь: Всегда закрывайте браузер или переходите к другой заметке перед обновлением.

Для получения дополнительной информации и других известных проблем см. полную документацию.

Устранение неполадок

Ошибка ERR_REQUIRE_ESM

Если вы видите ошибку вроде:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Это означает, что ваша версия Node.js не поддерживается. Серверу требуется Node.js 22.12.0+.

Примечание: Минимальная поддерживаемая версия среды выполнения — Node.js 22.12.0. Node.js 20 (Iron) достигла конца срока службы 30 апреля 2026 г. и больше не поддерживается.

Проверьте вашу версию:

node --version

Решение: Обновите Node.js до версии 22.12.0+. Вы можете скачать её с nodejs.org или использовать менеджер версий, например nvm.

Разработка

Режимы транспорта

Этот сервер поддерживает три транспортных режима MCP через отдельные точки входа:

Режим STDIO (по умолчанию)

Для локальных клиентов MCP, таких как Claude Desktop
Использует стандартный ввод/вывод для связи
Точка входа: dist/main-stdio.js
Запуск: npm run start:prod:stdio или node dist/main-stdio.js
Пакет MCPB: Использует режим STDIO

Режим HTTP (потоковый HTTP)

Для удалённых клиентов MCP и веб-интеграций
Использует протокол MCP Streamable HTTP
Точка входа: dist/main-http.js
Запуск: npm run start:prod:http или node dist/main-http.js
Порт по умолчанию: 3000 (настраивается через переменную окружения PORT)
Хост по умолчанию: 127.0.0.1 (настраивается через переменную окружения HOST)
Конечная точка MCP: http://127.0.0.1:3000/ (корневой путь)

Режим туннеля (управляемый туннель WebSocket)

Для веб-ассистентов с ИИ через управляемый туннельный сервис AnkiMCP со встроенной аутентификацией
Сервер MCP работает внутри процесса за транспортом в памяти; TunnelMcpService подключает его к серверу MCP, а TunnelClient соединяет его с туннельным сервисом через WebSocket
Точка входа: dist/main-tunnel.js
Запуск: node dist/main-tunnel.js --tunnel (или ankimcp --tunnel)
Аутентификация: ankimcp --login / ankimcp --logout; учётные данные хранятся в ~/.ankimcp/credentials.json (0600)
Разработка: npm run start:dev:tunnel (режим отслеживания, запускает --tunnel --debug)

Сборка

npm run build  # Builds once, creates dist/ with all three entry points

main-stdio.js, main-http.js и main-tunnel.js собираются в один каталог dist/. Выберите, какой запускать, исходя из ваших потребностей.

Конфигурация режима HTTP

Переменные окружения:

PORT — порт HTTP-сервера (по умолчанию: 3000)
HOST — адрес привязки (по умолчанию: 127.0.0.1, только для localhost)
ALLOWED_HOSTS — разделённый запятыми список дополнительных значений заголовка Host, принимаемых помимо встроенного набора loopback (localhost, 127.0.0.1, ::1). Только имя хоста, без учёта порта. По умолчанию: только loopback.
ALLOWED_ORIGINS — разделённый запятыми список разрешённых шаблонов Origin/Referer браузера; поддерживаются подстановочные знаки (например, https://*.ngrok.io). По умолчанию: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
LOG_LEVEL — уровень логирования (по умолчанию: info)

Безопасность:

Проверка заголовка Host (защита от DNS-ребендинга) — каждый HTTP-запрос должен содержать заголовок Host, соответствующий списку разрешённых. По умолчанию принимаются только хосты loopback (localhost, 127.0.0.1, ::1), независимо от порта. Host — это запрещённый для браузера заголовок, поэтому вредоносная веб-страница не может его подделать — это закрывает путь DNS-ребендинга, при котором страница после ребендинга обращается к серверу с поддельным Host и без Origin. Запрещённый Host отклоняется с кодом 403.
Проверка заголовка Origin — запросы браузера с присутствующим, но запрещённым заголовком Origin/Referer отклоняются. Запросы без заголовка Origin (curl, Postman, клиенты MCP-over-HTTP) разрешены; защитой от ребендинга является проверка Host.
По умолчанию привязывается к localhost (127.0.0.1).
В текущей версии нет аутентификации (поддержка OAuth планируется).

Предоставление доступа к режиму HTTP за пределами localhost — если вы привязываетесь к адресу LAN/публичному адресу или размещаете сервер за обратным прокси или публичным доменом, вы должны установить ALLOWED_HOSTS в имя хоста (имена), которые будут использовать клиенты, иначе каждый запрос не с loopback будет отклонён с кодом 403:

# Bind to all interfaces and accept the machine's LAN name + a public domain
ALLOWED_HOSTS=my-nas.local,anki.example.com PORT=8080 HOST=0.0.0.0 node dist/main-http.js

Когда вы привязываетесь к 0.0.0.0/:: без ALLOWED_HOSTS, сервер записывает в лог предупреждение при запуске о том, что будут приниматься только заголовки Host от loopback.

Docker / обратный прокси / публичный домен: применяется то же правило. В Docker запросы обычно приходят с опубликованным именем хоста контейнера или заголовком Host прокси, поэтому установите ALLOWED_HOSTS соответствующим образом. Обратный прокси (nginx, Caddy, Traefik) должен либо перенаправлять исходный заголовок Host и иметь это имя хоста в списке ALLOWED_HOSTS, либо перезаписывать вышестоящий заголовок Host на localhost. Встроенная интеграция --ngrok обрабатывает это автоматически (см. ниже).

Пример: Запуск режимов

# Development - STDIO mode (watch mode with auto-rebuild)
npm run start:dev:stdio

# Development - HTTP mode (watch mode with auto-rebuild)
npm run start:dev:http

# Production - STDIO mode
npm run start:prod:stdio
# or
node dist/main-stdio.js

# Production - HTTP mode
npm run start:prod:http
# or
PORT=8080 HOST=0.0.0.0 node dist/main-http.js

Сборка пакета MCPB

Чтобы создать распространяемый пакет MCPB:

npm run mcpb:bundle

Эта команда выполнит:

Синхронизацию версии из package.json в manifest.json
Удаление старых файлов .mcpb
Сборку проекта TypeScript
Упаковку dist/ и node_modules/ в файл .mcpb
Запуск mcpb clean для удаления devDependencies (оптимизирует пакет с ~47 МБ до ~10 МБ)

Выходной файл будет называться anki-mcp-server-X.X.X.mcpb и может распространяться для установки в один клик.

Что входит в пакет

Пакет MCPB включает:

Скомпилированный JavaScript (каталог dist/ — включает все три точки входа)
Только производственные зависимости (node_modules/ — devDependencies удалены с помощью mcpb clean)
Метаданные пакета (package.json)
Конфигурацию манифеста (manifest.json — настроена на использование main-stdio.js)
Значок (icon.png)

Исходные файлы, тесты и конфигурации разработки автоматически исключаются через .mcpbignore.

Логирование в Claude Desktop

При запуске в качестве расширения MCPB в Claude Desktop логи записываются в:

Расположение логов: ~/Library/Logs/Claude/ (macOS)

Логи разделены на несколько файлов:

main.log — общие логи приложения Claude Desktop
mcp-server-Anki MCP Server.log — сообщения протокола MCP для этого расширения
mcp.log — объединённые логи MCP со всех серверов

Примечание: Вывод логгера pino (сообщения INFO, ERROR, WARN из кода сервера) направляется в stderr и появляется в специфичных для MCP лог-файлах. Claude Desktop определяет, какой лог-файл получает какие сообщения, но обычно:

Запуск приложения и коммуникация по протоколу MCP → специфичный для MCP лог
Внутреннее логирование сервера (pino) → как специфичный для MCP лог, так и иногда main.log

Для просмотра логов в реальном времени:

tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log

Отладка сервера MCP

Вы можете отлаживать сервер MCP с помощью MCP Inspector и подключения отладчика из вашей IDE (WebStorm, VS Code и т.д.).

Примечание для режима HTTP: При тестировании режима HTTP (потоковый HTTP) с MCP Inspector используйте «Connection Type: Via Proxy», чтобы избежать ошибок CORS.

Шаг 1: Настройка отладочного сервера в MCP Inspector

mcp-inspector-config.json уже включает конфигурацию отладочного сервера:

{
  "mcpServers": {
    "stdio-server-debug": {
      "type": "stdio",
      "command": "node",
      "args": ["--inspect-brk=9229", "dist/main-stdio.js"],
      "env": {
        "MCP_SERVER_NAME": "anki-mcp-stdio-debug",
        "MCP_SERVER_VERSION": "1.0.0",
        "LOG_LEVEL": "debug"
      },
      "note": "Anki MCP server with debugging enabled on port 9229"
    }
  }
}

Шаг 2: Запуск отладочного сервера

Запустите MCP Inspector с отладочным сервером:

npm run inspector:debug

Это запустит сервер с включённой отладкой Node.js на порту 9229 и приостановит выполнение на первой строке.

Шаг 3: Подключение отладчика из вашей IDE

WebStorm

Перейдите в Run → Edit Configurations
Добавьте новую конфигурацию Attach to Node.js/Chrome
Установите порт 9229
Нажмите Debug для подключения

VS Code

Откройте панель отладки (Ctrl+Shift+D / Cmd+Shift+D)
Выберите конфигурацию Debug MCP Server (Attach)
Нажмите F5 для подключения

Шаг 4: Установка точек останова и отладка

После подключения вы можете:

Устанавливать точки останова в исходных файлах TypeScript
Выполнять код по шагам
Проверять переменные и стек вызовов
Использовать консоль отладки для вычисления выражений

Отладчик будет работать с картами исходного кода, позволяя отлаживать оригинальный код TypeScript, а не скомпилированный JavaScript.

Отладка с Claude Desktop

Вы также можете отлаживать сервер MCP, пока он работает внутри Claude Desktop, включив отладчик Node.js и подключив вашу IDE.

Шаг 1: Настройка Claude Desktop для отладки

Обновите конфигурацию Claude Desktop, чтобы включить отладку:

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

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": [
        "--inspect=9229",
        "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
      ],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Ключевое изменение: Добавьте --inspect=9229 перед путём к dist/main-stdio.js

Параметры отладки:

--inspect=9229 — немедленный запуск отладчика, без блокировки (рекомендуется)
--inspect-brk=9229 — приостановка выполнения до подключения отладчика (для отладки проблем при запуске)

Шаг 2: Перезапуск Claude Desktop

После сохранения конфигурации перезапустите Claude Desktop. Сервер MCP теперь будет работать с включённой отладкой на порту 9229.

Шаг 3: Подключение отладчика из вашей IDE

WebStorm

Перейдите в Run → Edit Configurations
Нажмите кнопку + и выберите Attach to Node.js/Chrome
Настройте:
- Name: Attach to Anki MCP (Claude Desktop)
- Host: localhost
- Port: 9229
- Attach to: Node.js < 8 или Chrome or Node.js > 6.3 (в зависимости от версии WebStorm)
Нажмите OK
Нажмите Debug (Shift+F9) для подключения

VS Code

Добавьте в .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Anki MCP (Claude Desktop)",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

Откройте панель отладки (Ctrl+Shift+D / Cmd+Shift+D)
Выберите Attach to Anki MCP (Claude Desktop)
Нажмите F5 для подключения

Шаг 4: Отладка в реальном времени

После подключения вы можете:

Устанавливать точки останова в исходных файлах TypeScript (например, src/mcp/primitives/essential/tools/create-model.tool.ts)
Использовать Claude Desktop в обычном режиме — точки останова сработают при вызове инструментов
Выполнять код по шагам
Проверять переменные и стек вызовов
Использовать консоль отладки

Пример: Установите точку останова в create-model.tool.ts на строке 119, затем попросите Claude создать новую модель. Отладчик остановится на вашей точке останова!

Примечание: Отладчик остаётся подключённым, пока работает Claude Desktop. Вы можете отключаться и подключаться в любое время без перезапуска Claude Desktop.

Команды сборки

npm run build              # Build the project (compile TypeScript to JavaScript)
npm run start:dev:stdio    # STDIO mode with watch (auto-rebuild)
npm run start:dev:http     # HTTP mode with watch (auto-rebuild)
npm run type-check         # Run TypeScript type checking
npm run lint               # Run ESLint
npm run mcpb:bundle        # Sync version, clean, build, and create MCPB bundle

Тестирование пакета NPM (локальное)

Протестируйте пакет npm локально перед публикацией:

# 1. Create local package
npm run pack:local         # Builds and creates @ankimcp/anki-mcp-server-*.tgz

# 2. Install globally from local package
npm run install:local      # Installs from ./@ankimcp/anki-mcp-server-*.tgz

# 3. Test the command
ankimcp                    # Runs HTTP server on port 3000

# 4. Uninstall when done testing
npm run uninstall:local    # Removes global installation

Как это работает:

npm pack создаёт файл .tgz, идентичный тому, что создала бы публикация npm
Установка из .tgz имитирует то, что пользователи получают из npm install -g ankimcp
Это позволяет протестировать полный пользовательский опыт перед публикацией в npm

Команды тестирования

npm test              # Run all tests
npm run test:unit     # Run unit tests only
npm run test:tools    # Run tool-specific tests
npm run test:workflows # Run workflow integration tests
npm run test:e2e      # Run end-to-end tests
npm run test:cov      # Run tests with coverage report
npm run test:watch    # Run tests in watch mode
npm run test:debug    # Run tests with debugger
npm run test:ci       # Run tests for CI (silent, with coverage)

Покрытие тестами

Проект поддерживает минимальные пороги покрытия в 70% для:

Ветвей
Функций
Строк
Операторов

Отчёты о покрытии генерируются в каталоге coverage/.

Версионирование

Этот проект следует Семантическому версионированию с подходом к разработке до версии 1.0:

0.x.x — Бета-версии / версии для разработки (текущая фаза)
- 0.1.x — Исправления ошибок и патчи
- 0.2.0+ — Новые функции или незначительные улучшения
- Критические изменения допустимы в версиях 0.x
1.0.0 — Первый стабильный релиз
- Будет выпущен, когда API станет стабильным и протестированным
- Критические изменения потребуют увеличения мажорной версии (2.0.0 и т.д.)

Текущий статус: 0.22.0 — Активная бета-разработка. Последние функции включают анализ повторений по всей коллекции (review_stats теперь агрегирует данные по всем колодам, если deck опущен), управление полями модели (addModelField, removeModelField, renameModelField, repositionModelField), пакетное создание заметок (addNotes), интегрированное туннелирование ngrok (флаг --ngrok), управление медиафайлами, управление моделями/шаблонами и комплексную статистику колод. API могут изменяться на основе отзывов и тестирования.

Развитие спецификации MCPB

Этот проект ориентирован на спецификацию пакетов MCPB от Anthropic, которая всё ещё развивается. Мы отслеживаем спецификацию на https://github.com/modelcontextprotocol/mcpb и можем вносить критические изменения для соответствия ей. Критические изменения разрешены в рамках схемы версионирования 0.x.x.

Полезные ссылки

Лицензия и указание авторства

Этот проект распространяется под лицензией MIT — полный текст см. в LICENSE.

Указание авторства третьих сторон

Anki® является зарегистрированной торговой маркой Ankitects Pty Ltd. Этот проект — неофициальный сторонний инструмент, не связанный с Ankitects Pty Ltd, не одобренный и не спонсируемый ею. Логотип Anki используется в соответствии с альтернативной лицензией для упоминания Anki со ссылкой на https://apps.ankiweb.net. Официальное приложение Anki доступно на https://apps.ankiweb.net.
Model Context Protocol (MCP) — открытый стандарт от Anthropic. Логотип MCP взят из официального репозитория документации MCP и используется под лицензией MIT. Для получения дополнительной информации о MCP посетите https://modelcontextprotocol.io.
Это независимый проект, объединяющий технологии Anki и MCP. Все торговые марки, знаки обслуживания, фирменные наименования, названия продуктов и логотипы являются собственностью их соответствующих владельцев.