AnkiPlus MCP
Provides Anki-focused helpers for card validation, previews, review change proposals, and preparation of Anki import payloads and artifacts. It does not connect to Anki or perform collection operations; prepared payloads are intended to be passed to the separate official Anki MCP.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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/lecturesinit 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 |
|
|
|
|
| A directory the server may read lectures from. Repeatable. |
| Where workspaces are kept. Defaults to your per-user data directory. |
|
|
| Show what would change and stop. |
| Do not ask for confirmation. |
| Print a generic config snippet for any other host and change nothing. |
| Machine-readable result on stdout. |
How each host is registered:
Host | What |
Claude Code | User scope runs |
Claude Desktop | Edits |
Codex | Runs |
OpenCode | Edits |
Hermes Agent | Prints the YAML to add to |
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 addedOCR 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 |
| Chromium if installed, else Google Chrome. The default. |
| Only Playwright's Chromium. |
| 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/lecturesThe 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/workspaceson macOS,~/.local/share/ankiplusmcp/workspaceson Linux). Override with--workspace-rootorANKIPLUS_WORKSPACE_ROOT.Readable source directories are taken from the first of these that is set:
--source-rootflags;ANKIPLUS_SOURCE_ROOTS(separated likePATH); 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 |
|
|
|
|
|
|
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 overrideRunning 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_cardsreplaces the complete workspace card set;expected_revisionprotects against lost edits.extract_source,export_figures,ocr_imageandrender_cardsreturn jobs. Useget_jobfor status/results andcancel_jobto request cancellation. Cancellation before publication preserves the current source/preview snapshot; a cancellation arriving after an atomic publication does not undo completed work.get_imagereturns an image block. Text and card lists have bounded results; follownext_offset, reduce the requested selection, or useread_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_reviewstores proposals;apply_changespreviews a diff by default. Applying changes is explicit. Reviews are optional and reviewer identities are labels supplied by the caller, not verified independence.prepare_writecreates 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_resultsstores supplied evidence. Reports label itcaller_suppliedand 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Make Anki flashcards from lecture PDFs, slides, notes and YouTube videos, each with its source page.
Spaced-repetition flashcards in Markdown: create cards, manage decks and study with FSRS.
Read, write, and conversationally review open-source flashcards through split read/write MCP tools.
Spaced-repetition flashcards your AI writes, quizzes you on by voice, and schedules with FSRS.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables safe, review-first Anki authoring with tools to inspect structure, create note types, add notes, preview renderings, and manage cards via AnkiConnect.166 npmMIT
- AlicenseAqualityDmaintenanceThe simplest and most stable MCP server for Anki, enabling LLMs to perform core Anki operations (CRUD) directly without addons.1317MIT
- AlicenseNot gradedqualityDmaintenanceBridge between AI assistants and Anki Desktop, enabling automated flashcard management and study document processing.446 npmMIT
- AlicenseNot gradedqualityDmaintenanceA 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