Anki MCP Server

Anki MCP Server

Seamlessly integrate Anki with AI assistants through the Model Context Protocol

[!IMPORTANT]

Prefer the [AnkiMCP addon](https://ankiweb.net/shared/info/124672614) for most setups.

The addon (GitHub) runs the MCP server directly inside Anki. There is no Node.js to install, no AnkiConnect to configure, no separate process to keep running: install it with code 124672614, restart Anki, and the server is up every time Anki opens. It covers local HTTP access and remote access through a built-in tunnel.

This repository is the right choice when you specifically need:

- STDIO transport — Claude Desktop, Claude Code, Cursor, or any client that spawns the server as a subprocess

- MCPB bundle — the one-click .mcpb install for Claude Desktop

For HTTP, tunnel, or web-based clients (claude.ai, ChatGPT), the addon is the simpler and better-supported path.

This repo is not being deprecated. It stays maintained and released alongside the addon as part of the same ankimcp.ai project.

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!

Examples and Tutorials

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

[ankimcp.ai](https://ankimcp.ai) - Complete documentation with practical examples and use cases

See docs/ for supplementary documentation, including the reviewer setup guide and the sample Anki deck.

Example Use Cases

Three representative prompts showing the tool flows this server enables:

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

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

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

Available Tools

The server exposes 53 MCP tools — 42 essential tools for everyday Anki operations and 11 GUI tools that drive the Anki desktop interface for note editing/creation workflows.

Essential Tools

Review & Study

• 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 (answers omitted unless include_answer: true, default false)
• get_cards - Get cards with flexible filtering by state (due, new, learning, suspended, buried) and deck (answers omitted unless include_answer: true, default false)
• 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
• forgetCards - Reset cards to new, discarding their scheduling without recording a review
• setDueDate - Reschedule cards to become due in N days ("0", "3-7", "1!"), without recording a review
• areSuspended - Check suspension state for one or more cards without changing anything
• suspend - Suspend cards so they are skipped during review until unsuspended
• unsuspend - Unsuspend cards so they return to normal review

Note: forgetCards and setDueDate change scheduling *without* logging a review, which is what separates them from rate_card. Reach for them when a card's schedule is wrong rather than the answer: rating a card Again to bury it deeper records a real lapse and drops its ease factor, permanently skewing both future scheduling and your statistics. forgetCards wipes the interval and starts the card over; setDueDate keeps the card's history and just moves the next review.

Note: Card front/back content 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.

Deck Management

• 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 (supports Parent::Child, max 2 levels)
• changeDeck - Move cards to a different deck (created if it doesn't exist)

Note: Deck statistics come in two flavours. The counts block (and everything listDecks reports) mirrors Anki's deck browser: cards due today, capped by each deck's daily new/review limits, with suspended and buried cards excluded — so review is not "mature cards" and the other bucket is just the arithmetic remainder (mostly review cards not due today plus new cards over the daily limit). For true per-state totals use the states block on deckStats / collection_stats, which counts new, learning, review, suspended and buried via Anki searches, ignoring due dates and daily limits.

Note Management

• 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, note type, card IDs; CSS comes from modelStyling)
• updateNoteFields - Update existing note fields (CSS-aware, supports HTML content)
• deleteNotes - Delete notes and all associated cards (destructive, requires confirmation)

Tag Management

• 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)

Media Management

• getMediaFilesNames - List media files in collection.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 from collection.media (destructive)

💡 Best Practice for Images:

• ✅ 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

Just tell Claude where the image is, and it will handle the upload automatically using the most efficient method.

Model/Template Management

• 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 (Anki rewrites references to the old name in the card templates)
• repositionModelField - Change the position of a field within an existing note type

Statistics

• 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)

GUI Tools

Tools that drive the Anki desktop interface. Intended for note editing/creation and deck-management workflows, not for review sessions.

• 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 (includes the answer; errors outside 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

Prerequisites

• Anki with AnkiConnect plugin installed
• Node.js 22.12.0+

Installation

There are a few ways to get the server onto your machine. Once it's installed, head to Connecting an AI Client to wire it up to your AI assistant — locally or remotely.

npm (global or npx)

The general-purpose way to install the server, suitable for any MCP client that launches it directly.

Install it globally for clients that run the ankimcp command:

npm install -g @ankimcp/anki-mcp-server

Or run it on demand with no install required:

npx @ankimcp/anki-mcp-server

MCPB Bundle (Recommended for Claude Desktop)

The easiest way to install this MCP server for Claude Desktop:

1. Download the latest .mcpb bundle from the Releases page
2. In Claude Desktop, install the extension:

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

1. Configure AnkiConnect URL if needed (defaults to http://localhost:8765)
2. Restart Claude Desktop

That's it! The bundle includes everything needed to run the server locally.

For Anthropic MCP Directory reviewers: a zero-to-integration walkthrough with a pre-populated sample deck lives in docs/reviewer-setup.md.

Install from Source (for development)

For development or advanced usage (running t