Skip to main content
Glama

AnkiPlus MCP

ankiplusmcp gives a model independent mechanical helpers for lecture extraction, OCR, image occlusions, card validation, previews, review changes and Anki payload preparation. The model chooses which tools to use. There is no mandatory pipeline, review panel or model provider.

The official Anki MCP is a separate companion dependency. Configure both in your AI host. AnkiPlus never connects to Anki, proxies that server, or performs collection operations. The model passes snapshots and prepared payloads between the servers. Source-only and supplied-card operations also work offline.

Derived from Lecture2Cards. Its cards CLI remains available with its original gate and semantics. See the legacy guide and capability mapping.

Install

You need Node 18 or newer and uv. uv fetches Python and the server's dependencies for you. macOS and Linux are supported; Windows is untested.

Register the server in your AI host with one command:

npx -y github:Hamza-Xoho/ankiplusMCP#v0.3.0 init --host claude-code --source-root /absolute/lectures

init shows every change before it makes it, backs up any file it edits, and installs the companion skill where the host has a place for one. It never replaces an existing ankiplusmcp entry or a skill copy you have edited unless you pass --force. It finishes by starting the server once, because the very first start downloads dependencies and can take a minute or more.

Flag

Meaning

--host

claude-code, claude-desktop, codex, opencode or hermes. Needed when more than one is installed.

--scope

user (default) or project, where the host supports project config.

--source-root DIR

A directory the server may read lectures from. Repeatable.

--workspace-root DIR

Where workspaces are kept. Defaults to your per-user data directory.

--profile NAME

default or coldrecall (see Profiles).

--dry-run

Show what would change and stop.

--yes

Do not ask for confirmation.

--print

Print a generic config snippet for any other host and change nothing.

--json

Machine-readable result on stdout.

How each host is registered:

Host

What init does

Claude Code

User scope runs claude mcp add; project scope edits .mcp.json. Skill goes to .claude/skills/.

Claude Desktop

Edits claude_desktop_config.json.

Codex

Runs codex mcp add.

OpenCode

Edits opencode.json (mcp.servers, the v2 layout).

Hermes Agent

Prints the YAML to add to ~/.hermes/config.yaml; it does not edit YAML.

Registration is covered by automated tests against sample config files. On a real machine only Claude Code has been tried, and only as a dry run; treat the others as untested until you have run them once.

The other commands:

npx -y github:Hamza-Xoho/ankiplusMCP#v0.3.0 doctor      # what is missing, and the command that fixes it
npx -y github:Hamza-Xoho/ankiplusMCP#v0.3.0 setup       # download Chromium for card previews (asks first)
npx -y github:Hamza-Xoho/ankiplusMCP#v0.3.0 uninstall   # remove exactly what init added

OCR needs the Tesseract program (brew install tesseract, or sudo apt-get install -y tesseract-ocr). Card previews need a browser: either Chromium, which setup installs, or Google Chrome. If Google Chrome is installed, you do not need to run setup. Everything else works without either, and a tool that needs a missing one returns a DEPENDENCY error naming the fix.

Choosing the preview browser

By default (auto) the server uses Playwright's Chromium when it is installed, and otherwise Google Chrome. To choose, pass --browser to serve, doctor or setup, or set browser in config.toml. The flag wins over the file. All three also take --config to name the config file. setup downloads Chromium only when the chosen setting finds no browser.

Value

Meaning

auto

Chromium if installed, else Google Chrome. The default.

chromium

Only Playwright's Chromium.

chrome

Only the installed Google Chrome.

An absolute path

That browser program. The file must exist.

browser = "chrome"

doctor shows which browser it found, and setup --json and the capabilities tool report it too.

Without npx

The launcher only finds uv and starts the Python program. You can do that yourself:

uvx --from "ankiplusmcp[all] @ git+https://github.com/Hamza-Xoho/ankiplusMCP@v0.3.0" ankiplusmcp --source-root /absolute/lectures

The server speaks MCP over stdio. It is not an HTTP server and opens no port. No credentials or model API key are needed.

Where things go

  • Workspaces live in your per-user data directory (~/Library/Application Support/ankiplusmcp/workspaces on macOS, ~/.local/share/ankiplusmcp/workspaces on Linux). Override with --workspace-root or ANKIPLUS_WORKSPACE_ROOT.

  • Readable source directories are taken from the first of these that is set: --source-root flags; ANKIPLUS_SOURCE_ROOTS (separated like PATH); the folders your host offers as MCP roots; the directory the server was started in, unless that is / or your home directory. If none applies the server can read no source files and says so.

Only requested sources are copied into a workspace; original files are never changed. Native OCR and rendering cancel at operation boundaries, not by interrupting Tesseract or Chromium mid-run.

Profiles

A profile sets the note type used when a card does not name one, and the root of suggested tags.

Profile

Note type

Tag root

default

Cloze (Anki's own)

#AnkiPlus

coldrecall

ColdRecall Cloze

#ColdRecall

Choose one with --profile, or put a config.toml in your per-user config directory (or point --config / ANKIPLUS_CONFIG at one):

profile = "coldrecall"   # optional starting point
note_type = "My Cloze"   # optional override
tag_root = "#Medicine"   # optional override

Running unattended

Every launcher command can run with no person present. Pass --yes to skip confirmation and --json for output a program can read. Without a terminal and without --yes, a command that would ask a question exits at once instead of waiting. Exit codes: 0 done, 1 declined or only optional tools missing, 2 error or a required item missing, 3 refused (pass --yes or --force, or follow the printed manual step).

Licences

This project is MIT-licensed. It depends on PyMuPDF, which is AGPL-licensed (a commercial licence is sold separately by its authors). PyMuPDF is installed from PyPI on your machine and is not redistributed here. If you ship software that includes it, read its terms.

Related MCP server: Mousetail

Using the toolkit

Ask for the outcome you want, for example “make cards from these slides”, “show me previews of these existing cards”, or “occlude labels on this figure”. Tool descriptions and typed inputs describe what each helper needs. capabilities reports dependencies and get_guidance optionally supplies examples/quality rubrics. The companion skill is optional; init installs it for hosts that have a skill directory.

  • Every workspace has an explicit ID and revision. save_cards replaces the complete workspace card set; expected_revision protects against lost edits.

  • extract_source, export_figures, ocr_image and render_cards return jobs. Use get_job for status/results and cancel_job to request cancellation. Cancellation before publication preserves the current source/preview snapshot; a cancellation arriving after an atomic publication does not undo completed work.

  • get_image returns an image block. Text and card lists have bounded results; follow next_offset, reduce the requested selection, or use read_artifact.

  • Existing-note snapshots can have arbitrary field names. Supply note-type templates/CSS or actual question/answer HTML from Anki MCP for closer previews. Anki's full template engine, custom filters and add-on JavaScript are not emulated.

  • submit_review stores proposals; apply_changes previews a diff by default. Applying changes is explicit. Reviews are optional and reviewer identities are labels supplied by the caller, not verified independence.

  • prepare_write creates payload and import artifacts without writing to Anki. Pass their contents to the official Anki MCP. Note IDs and card IDs remain distinct; suspension requires actual card IDs, sometimes resolved after creation.

  • record_external_results stores supplied evidence. Reports label it caller_supplied and never claim independent Anki verification.

House-style and lecture-coverage checks are optional; technical validation always applies to prepared payloads. Neither checks nor AI reviews establish factual accuracy. Legacy build files are not silently migrated into new workspaces.

Development and checks

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/python -m playwright install chromium
./scripts/check-mcp.sh        # Python tests, frozen-contract hashes, wheel build
npm test                      # launcher tests (Node 18+, no dependencies)

The npm launcher lives in launcher/; it has no runtime dependencies. Its version in package.json must equal the one in pyproject.toml (scripts/check_versions.py), because the launcher installs the Python package tagged with its own version. To run the launcher against your checkout, set ANKIPLUSMCP_PY_SPEC="ankiplusmcp[all] @ file://$PWD".

Tests use synthetic sources/cards, real Chromium, OCR and an SDK stdio client. The default check includes the original unit suite and synthetic foundational contracts. Private lecture contract fixtures are not shipped: their absence is reported as an untested limitation, not hidden by changing frozen tests.

Optional stdio container

# Set revision accurately, including the dirty suffix for local changes.
ANKIPLUS_REVISION="$(git rev-parse --short HEAD)"
if test -n "$(git status --porcelain)"; then ANKIPLUS_REVISION="$ANKIPLUS_REVISION-dirty"; fi
export ANKIPLUS_REVISION
export ANKIPLUS_SOURCES=/absolute/lectures
docker compose -p ankiplusmcp config --quiet
docker compose -p ankiplusmcp build
./scripts/run-container.sh "$ANKIPLUS_REVISION" "$ANKIPLUS_SOURCES"

This runs an isolated stdio process; it publishes no ports, uses no gateway and contacts no Anki server. The container is non-root, uses a read-only filesystem, limited resources, dropped capabilities and no-new-privileges. Source files are mounted read-only at /sources; persistent workspaces use the project volume. Configure the host to run scripts/run-container.sh with the image revision and source directory as arguments if using this transport. The wrapper refuses a missing image so build logs cannot enter MCP stdout. Existing media must be imported from the source mount, not arbitrary host paths.

Upstream attribution and MIT terms are retained in LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables safe, review-first Anki authoring with tools to inspect structure, create note types, add notes, preview renderings, and manage cards via AnkiConnect.
      16
      6 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A headless, sync-native Anki MCP sidecar that lets AI agents safely manage a real Anki collection without Anki Desktop or AnkiConnect, supporting sync with AnkiWeb or self-hosted servers.
      MIT