flashdeck

flashdeck

flashdeck lets an agent study and manage Anki flashcards through a local Anki instance running AnkiConnect. It covers the review loop (due cards, presenting a card, rating it), decks, notes, tags, note types, and collection statistics — a labelled core subset of 20 tools from the 53 documented in the original Anki MCP spec.

Anki must be running with the AnkiConnect add-on installed. By default flashdeck talks to http://127.0.0.1:8765; set ANKICONNECT_URL to point elsewhere.

Install

npx @reneturcios/flashdeck check

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/flashdeck

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead. Note the container still needs network access to the host's AnkiConnect endpoint.

CLI

flashdeck check           # probe AnkiConnect (deck list on success)
flashdeck decks           # list decks
flashdeck due [deck]      # due cards, optionally for one deck
flashdeck stats [deck]    # deck stats, or collection stats with no deck
flashdeck tags            # all tags
flashdeck models          # all note types
flashdeck sync            # sync with AnkiWeb
flashdeck --version

Most commands accept --json. Exit codes: 0 success, 1 error (the message names the AnkiConnect or validation problem), 2 usage error.

MCP server

npx -y @reneturcios/flashdeck mcp

MCP client configuration:

{
  "mcpServers": {
    "flashdeck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/flashdeck", "mcp"]
    }
  }
}

Tools

Tool	Input	What it does
sync	—	Sync with AnkiWeb.
get_due_cards	deck?, include_answer?	Due cards, optional deck filter; answers omitted unless requested.
get_cards	deck?, state?, include_answer?	Cards filtered by state (due/new/learning/suspended/buried) and deck.
present_card	card_id	Show a card's question/front.
rate_card	card_id, ease (1-4)	Rate Again/Hard/Good/Easy and schedule next review.
listDecks	include_stats?	List decks, optional per-deck stats.
deckStats	deck	Statistics for one deck.
createDeck	deck	Create a deck (Parent::Child, max 2 levels).
addNote	deck_name, model_name, fields, tags?	Create one note.
addNotes	deck_name, model_name, notes	Batch-create up to 100 notes.
findNotes	query	Search notes with Anki query syntax.
notesInfo	notes	Details for notes.
updateNoteFields	note_id, fields	Update a note's fields.
deleteNotes	notes, confirm?	Delete notes; refused without confirm: true.
getTags	—	All tags.
addTags	notes, tags	Add tags to notes.
removeTags	notes, tags	Remove tags from notes.
modelNames	—	List note types.
modelFieldNames	model_name	Field names for a note type.
collection_stats	—	Aggregated collection statistics.

Deck statistics are computed locally from per-state card searches; no statistics endpoint is assumed. When Anki is not running, tools return an error naming the failed AnkiConnect request rather than an empty result.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no live Anki
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.