Anki Mcp Desktop

Anki MCP Server

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!

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 - 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 syncs 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.

2. "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).

3. "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 <img> tag (updateNoteFields).

Available Tools

The server exposes 42 MCP tools — 31 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
• 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

Deck Management

• listDecks - List all decks, optionally with per-deck card-count statistics
• deckStats - Get comprehensive statistics for a single deck (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 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, CSS styling)
• 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 (card templates referencing the old name must be updated separately)
• repositionModelField - Change the position of a field within an existing note type

Statistics

• collection_stats - Aggregated statistics across all decks with per-deck breakdown
• 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
• 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
3. Configure AnkiConnect URL if needed (defaults to http://localhost:8765)
4. 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:

npm install
npm run build

Connecting an AI Client

There are two ways an AI assistant can reach this server, depending on where the assistant runs:

• Local — the server runs on the same machine as the AI client (Claude Desktop, Cursor, Cline, Zed, or a local browser session). Use STDIO for desktop MCP clients, HTTP for local web-based tools.
• Remote — a hosted/remote AI (e.g. ChatGPT or Claude.ai in the cloud) needs to reach the Anki running on your local machine. Use the managed Tunnel (✅ recommended — authenticated) or, as a lighter-weight unauthenticated alternative, ngrok.

Local

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

STDIO (primary local integration)

STDIO is the standard transport for local desktop MCP clients — Claude Desktop, Cursor IDE, Cline, Zed Editor, and others. The client launches the server as a subprocess and communicates over standard input/output.

Supported Clients:

• Claude Desktop
• Cursor IDE - AI-powered code editor
• Cline - VS Code extension for AI assistance
• Zed Editor - Fast, modern code editor
• Other MCP clients that support STDIO transport

For Claude Desktop, the MCPB bundle is the easiest path. For other clients, configure the npm package with the --stdio flag.

Configuration - Choose one method:

Method 1: Using npx (recommended - no installation needed)

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Method 2: Using global installation

First, install globally:

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

Then configure:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Configuration file locations:

• Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)
• Cline: Accessible via settings UI in VS Code
• Zed Editor: Install as MCP extension through extension marketplace

For client-specific features and troubleshooting, consult your MCP client's documentation. See also Connect to Claude Desktop for a config that points directly at a built dist/main-stdio.js.

HTTP (local web-based AI)

HTTP mode runs the server as a local web server speaking the MCP Streamable HTTP protocol. It's the transport a web-based AI tool talks to when pointed at your machine, and it's also what the Remote options expose to the outside world. On its own, HTTP mode binds to localhost only.

**Binding beyond l

…