anki-librarian-mcp
# anki-librarian-mcp
Public version of the flashcard workflow I use in my own studies: Claude turns study material into Anki cards and
manages the collection, without ever writing anything you have not approved.
**[Live demo](https://gcabralcavalcanti.github.io/anki-librarian-mcp/)**: the step-by-step simulation, built from this repository on every push.
## What it shows
- **From notes to cards in one request.** Claude sums up what the material teaches, plans the cards, writes them
and tags them, shown step by step for dense econometrics notes and for a business case.
- **No duplicates.** Before planning, it searches your whole collection and shows the card you already have.
- **Nothing is written without you.** Every change is a plan you approve first; deleting and rescheduling stay off
unless you turn them on.
## Run it
```
pip install -r requirements.txt
python demo.py
```
Runs without an API key, replaying recorded answers. Set `ANTHROPIC_API_KEY` and add `--live` to call Claude live.
It uses a practice collection; your Anki is not touched.
## How I use it
Most of my cards come from a weekly radar of news and data by topic, prepared by a scheduled task on Thursday
night; I pick from its menu and approve the cards. The rest come from quick questions, the end of a project and
dense study material. The radar does not run by itself: you ask for it or schedule it
([how](docs/how-it-works.md#schedule-the-radar)).
## More
- [How it works](docs/how-it-works.md): how I use it, each step, the safety rules, installing it for Claude
Desktop or Claude Code, and how to start on your own collection with a test deck.
- [Runbook](RUNBOOK.md): commands, updating, and what to do when something breaks.
- The other side of the flashcards, how much review time each deck needs in the week, is in
[personal-ai-agents](https://github.com/gcabralcavalcanti/personal-ai-agents) (study blocks).
## Limits
- Pictures only, no audio or video.
- "Similar" means shared words and phrases; a card on the same idea in completely different words can be missed.
- Tested against a practice collection that behaves like Anki; try it on a test deck of your own first.
## How AI was used
I use Claude (Claude Code and the API) for coding, review and documentation. The questions, modelling choices,
validation and conclusions are mine.
## License
MIT, Guilherme Cabral.
TDQS
Scored across 13 tools
Each tool targets a distinct action and resource: read tools (list_decks, find_notes, get_notes), propose tools for different mutations (add notes, add cloze, update, create deck, delete, set due date, flag), and plan lifecycle tools (list_plans, apply_plan, reject_plan). find_notes (search excerpts) vs get_notes (full fields) are clearly separated, and the propose_* tools differ by object and operation.
Strong, predictable verb_noun pattern throughout, with a consistent propose_* prefix for dry runs and matching apply_plan/reject_plan lifecycle verbs. Minor deviations like singular vs plural (propose_update_note vs propose_add_notes) keep it just short of perfect.
13 tools is well-scoped for the Anki domain. The propose/apply split is intentional and each tool earns its place by covering a specific mutation or query without redundancy.
Covers a full lifecycle: deck/note discovery, note and cloze creation, updates, deletion, scheduling, flagging, and plan management. Minor gaps like moving notes between decks or deleting decks are absent but not blocking for core workflows.