Anki MCP

Beta- This project is in active development. APIs and features may change.

A Model Context Protocol (MCP) server that enables AI assistants to interact with Anki, the spaced repetition flashcard application.

Transform your Anki experience with natural language interaction - like having a private tutor. The AI assistant doesn't just present questions and answers; it can explain concepts, make the learning process more engaging and human-like, provide context, and adapt to your learning style. It can create and edit notes on the fly, turning your study sessions into dynamic conversations. More features coming soon!

For comprehensive guides, real-world examples, and step-by-step tutorials on using this MCP server with Claude Desktop, visit:

Three representative prompts showing the tool flows this server enables:
-

"Help me review my Spanish deck."— The assistant syncs with AnkiWeb (sync), fetches due cards (get_due_cardswith deck filter), presents each card (present_card), and records your rating (rate_card). Natural study conversation with explanations tailored to you.

"Create 10 Arabic vocab cards with RTL styling."— The assistant lists note types (modelNames), creates a custom RTL model if needed (createModel+updateModelStylingfor right-to-left CSS), then batch-creates the cards (addNotes).

"Import this image from my Downloads folder into the front of the selected note."— The assistant uploads the local file (storeMediaFilewith a file path), reads the currently-selected note from the browser (guiSelectedNotes+notesInfo), and updates the front field with an`tag (updateNoteFields).

- sync- Sync with AnkiWeb to pull latest data and push changes
- get_due_cards- Get cards that are due for review, optionally filtered by deck
- get_cards- Get cards with flexible filtering by state (due, new, learning, suspended, buried) and deck
- present_card- Show a card for review with its question/front side
- rate_card- Rate card performance (Again, Hard, Good, Easy) and schedule the next review

Note:Cardfront/backcontent is rendered per card from its own template (as Anki shows it), so reversed and cloze cards display the correct direction. Static text added by your card templates appears in the output as well.

- listDecks- List all decks, optionally with per-deck study-queue statistics
- deckStats- Get comprehensive statistics for a single deck (study queue, true card-state counts, ease/interval distributions)
- createDeck- Create a new empty deck (supportsParent::Child, max 2 levels)
- changeDeck- Move cards to a different deck (created if it doesn't exist)

Note:Deck statistics come in two flavours. Thecountsblock (and everythinglistDecksreports) mirrors Anki's deck browser: cardsdue today, capped by each deck'sdaily new/review limits, with suspended and buried cards excluded — soreviewis not "mature cards" and theotherbucket is just the arithmetic remainder (mostly review cards not due today plus new cards over the daily limit). For true per-state totals use thestatesblock ondeckStats/collection_stats, which countsnew,learning,review,suspendedandburiedvia Anki searches, ignoring due dates and daily limits.

- addNote- Create a single note with specified fields and tags
- addNotes- Batch-create up to 100 notes sharing a deck and model (partial success supported)
- findNotes- Search for notes using Anki query syntax (deck:,tag:,is:due, etc.)
- notesInfo- Get detailed information about notes (fields, tags, CSS styling)
- updateNoteFields- Update existing note fields (CSS-aware, supports HTML content)
- deleteNotes- Delete notes and all associated cards (destructive, requires confirmation)

- getTags- Get all tags in the collection (use first to avoid duplication)
- addTags- Add space-separated tags to specified notes
- removeTags- Remove space-separated tags from specified notes
- replaceTags- Rename a tag across specified notes
- clearUnusedTags- Remove orphaned tags not used by any notes (destructive)

- getMediaFilesNames- List media files incollection.media, optionally filtered by pattern
- retrieveMediaFile- Download a media file as base64 content
- storeMediaFile- Upload media from base64 data, an absolute file path, or a URL
- deleteMediaFile- Remove a media file fromcollection.media(destructive)

- ✅Use file paths(e.g.,/Users/you/image.png) - Fast and efficient
- ✅Use URLs(e.g.,https://example.com/image.jpg) - Direct download
- ❌Avoid base64- Extremely slow and token-inefficient

- modelNames- List all available note types/models
- modelFieldNames- Get field names for a specific note type
- modelStyling- Get CSS styling information for a note type
- modelTemplates- Get the card templates (Front and Back HTML) for a note type
- createModel- Create a new note type with custom fields, card templates, and CSS (e.g., RTL models)
- updateModelStyling- Update the CSS styling for an existing note type (applies to all its cards)
- updateModelTemplates- Update the card templates (Front and Back HTML) for an existing note type (applies to all its cards)
- addModelField- Add a new field to an existing note type (appended at the end or inserted at a specific position)
- removeModelField- Remove a field from an existing note type (deletes its content from all notes; requires explicit confirmation)
- renameModelField- Rename a field in an existing note type (card templates referencing the old name must be updated separately)
- repositionModelField- Change the position of a field within an existing note type

- collection_stats- Aggregated statistics across all decks with per-deck breakdown and collection-wide card-state counts
- review_stats- Review history analysis (temporal patterns, retention metrics, study streaks)

- guiBrowse- Open the Card Browser and search for cards
- guiSelectCard- Select a specific card in the Card Browser
- guiSelectedNotes- Get IDs of notes currently selected in the Card Browser
- guiAddCards- Open the Add Cards dialog with preset note details
- guiEditNote- Open the note editor for a specific note
- guiDeckOverview- Open the Deck Overview dialog for a specific deck
- guiDeckBrowser- Open the Deck Browser dialog
- guiCurrentCard- Get info about the current card in review mode
- guiShowQuestion- Show the question side of the current card
- guiShowAnswer- Show the answer side of the current card
- guiUndo- Undo the last action in Anki

Install it globally for clients that run theankimcpcommand:

- Method 1: Go to Settings → Extensions, then drag and drop the.mcpbfile
- Method 2: Go to Settings → Developer → Extensions → Install Extension, then select the.mcpbfile

The server runs on the same computer as your AI client and talks to AnkiConnect onlocalhost.

A hosted/remote AI (such as ChatGPT or Claude.ai running in the cloud) can't reachlocalhostdirectly. These options expose yourlocalAnki to the internet so a remote assistant can talk to it.

Tunnel mode lets web-based AI assistants reach yourlocalAnki without running your own tunnel. The server connects out to the managed AnkiMCP tunnel service (wss://tunnel.ankimcp.ai) over a WebSocket and is assigned a public URL. Authentication is built in — no ngrok account or separate tunnel process required, and you log in once.

Tunnel mode uses the OAuth 2.0 Device Authorization Grant. Logging in opens your browser automatically to an approval page with the code already embedded in the URL — nothing to type, just approve. (If the browser can't open, the terminal prints a verification URL and code to enter manually as a fallback.) On success, credentials are saved to~/.ankimcp/credentials.json(file permissions0600).

# 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

If no credentials exist,--tunnelautomatically starts the login flow first, then continues to the tunnel. This auto-login requires an interactive terminal — when stdout is not a TTY (systemd, headless Docker, CI), the server fast-fails and asks you to runankimcp --loginfirst. Once connected, the public tunnel URL is printed; press Ctrl+C to disconnect. Share that URL with your AI assistant.

The device-flow auth endpoints (/auth/device,/auth/token) are derived fromTUNNEL_SERVER_URL, so pointing--tunnel(orTUNNEL_SERVER_URL) at a different host also moves authentication to that host.

How it works:Tunnel mode runs the MCP server in-process behind an in-memory transport (TunnelTransport). That transport owns the MCP server and turns each relayed request body into a response, andTunnelClientbridges it to the remote tunnel service over a WebSocket — relaying MCP requests in and responses out. AnkiConnect is still only ever reached on your local machine.