ankimcp/anki-mcp-server

Anki MCP Server – What It Is

Anki MCP Server is a Node‑JS service that implements the Model Context Protocol (MCP). It sits between an AI assistant (Claude, Cursor, Cline, Zed, etc.) and the Anki spaced‑repetition app (via the AnkiConnect plugin). By exposing a rich set of “tools” – actions such as list decks, fetch due cards, create notes, upload media, and even GUI commands that drive Anki’s desktop windows – the server lets a language model talk to your personal flash‑card collection as if it were a conversational tutor.

Why It Exists

• AI‑driven study – ask an assistant to review a deck, generate new cards, or add images without leaving the chat.
• Standardised transport – MCP defines a JSON‑over‑STDIO or HTTP API that many AI‑client products already understand.
• Separate from Anki – the server runs outside Anki, so any AI client that can launch a subprocess or call a local web server can use it.

When to Use This Repo vs. the Add‑on

• Use the AnkiMCP add‑on (installed inside Anki) for the simplest, all‑in‑one experience (HTTP, remote tunnel, no Node.js needed).
• Use this stand‑alone server when you need:
  • STDIO transport – required by Claude Desktop, Cursor, Cline, Zed, etc.
  • MCPB bundle – a one‑click installer for Claude Desktop.

---

Core Features (as listed in the README)

Category	Tools (selected)	What It Does
Review & Study	sync, get_due_cards, present_card, rate_card, forgetCards, setDueDate	Sync with AnkiWeb, fetch cards due for review, show a card, record a rating, or manually adjust scheduling.
Deck Management	listDecks, deckStats, createDeck, changeDeck	List decks, get detailed statistics, create new decks (supports two‑level hierarchy), move cards between decks.
Note Management	addNote, addNotes, findNotes, notesInfo, updateNoteFields, deleteNotes	Create single or batch notes, search with Anki query syntax, read or edit note fields, delete notes.
Tag Management	getTags, addTags, removeTags, replaceTags, clearUnusedTags	Retrieve, add, remove, rename, or clean up tags.
Media Management	getMediaFilesNames, retrieveMediaFile, storeMediaFile, deleteMediaFile	List, download (base64), upload (path, URL or base64), or delete media files. The README recommends using file paths or URLs for speed.
Model / Template Management	modelNames, modelFieldNames, modelStyling, modelTemplates, createModel, updateModelStyling, addModelField …	Inspect, create, or modify note types (models), their fields, CSS styling, and card templates.
Statistics	collection_stats, review_stats	Global collection stats and review‑history analysis.
GUI Tools (not for review)	guiBrowse, guiAddCards, guiEditNote, guiDeckOverview, guiCurrentCard, guiUndo	Commands that open Anki’s desktop windows or act on the UI, useful for interactive workflows.

The server currently offers 53 tools (42 essential + 11 GUI). Each tool is invoked via the MCP JSON protocol and returns structured data that an AI can parse and act upon.

---

How to Get It Running

1. Prerequisites – Install Anki, add the AnkiConnect plugin, and have Node 22.12+.
2. Installation options
   • npm (global or npx) – npm install -g @ankimcp/anki-mcp-server then run ankimcp, or run on‑the‑fly with npx @ankimcp/anki-mcp-server.
   • MCPB bundle – download the .mcpb file from the GitHub releases page and install it in Claude Desktop (drag‑and‑drop or via Settings → Extensions).
   • From source – clone, npm install, npm run build.
3. Choose a transport
   • STDIO – best for desktop AI clients. The client launches the server as a subprocess (ankimcp --stdio). Configuration snippets are provided for Claude Desktop, Cursor, Cline, Zed, and opencode.
   • HTTP – runs a local web server (ankimcp defaults to localhost:3000). Useful for web‑based AI tools.
4. Remote access (if your AI runs in the cloud)
   • Tunnel (recommended) – ankimcp --tunnel connects to a managed WebSocket tunnel service, authenticates via OAuth device flow, and gives you a public URL you can give to ChatGPT, Claude.ai, etc.
   • ngrok – an alternative, unauthenticated option (not detailed in the README).

---

Typical Use‑Case Flow (from the README examples)

1. Review a deck – AI sends sync, then get_due_cards (maybe filtered by deck), iterates over the returned cards with present_card, and after each answer calls rate_card.
2. Create new cards – AI calls modelNames to pick a note type, optionally createModel for RTL Arabic, then addNotes with the desired fields.
3. Add an image – AI uploads a local file via storeMediaFile, fetches the currently selected note with guiSelectedNotes + notesInfo, and updates the front field using updateNoteFields to embed an <img> tag.

---

Who Might Benefit?

• Learners who want a conversational tutor that can fetch, explain, and edit flashcards on the fly.
• Developers building custom AI agents that need programmatic access to a personal Anki collection.
• Educators who want to automate bulk note creation or media management via LLM‑driven scripts.

---

Limitations & Caveats (as per the README)

• The server requires AnkiConnect – it does not talk to Anki directly.
• Some tools (e.g., forgetCards, setDueDate) modify scheduling without recording a review, which can affect long‑term statistics.
• Remote access needs either the managed tunnel (recommended) or a separate tunnelling solution; exposing Anki directly to the internet is discouraged.
• For most users, the AnkiMCP add‑on is simpler; this repository is mainly for those who need STDIO or the MCPB bundle.

---

Quick Start (STDIO via npx)

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

Place the JSON in the appropriate config file for your AI client (e.g., ~/.cursor/mcp.json for Cursor) and the client will launch the server automatically.

---

In short: Anki MCP Server is a Node‑based bridge that lets modern LLM‑powered assistants read, edit, and manage your Anki flashcards through a well‑defined protocol, supporting both local STDIO and remote HTTP/tunnel connections.