anki-mcp

MCP server that exposes Anki as tools for Claude and other LLM clients. Powered by AnkiConnect.

Create notes, search your collection, review due cards, manage decks, track retention — all from your LLM client.

Prerequisites

1. Anki must be running on the local machine.

2. AnkiConnect add-on must be installed: Anki → Tools → Add-ons → Get Add-ons → code 2055492159.

   • Default port: 8765. Do not change it.

3. Node.js 18+.

Related MCP server: Anki MCP Server

Quick start

npm install
npm run build   # tsc → dist/
npm start       # stdio transport

Development (no build step):

npm run dev     # tsx src/index.ts

Claude Desktop integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["/absolute/path/to/anki_mcp/dist/index.js"]
    }
  }
}

Available tools

AnkiConnect conventions

• ID types: Note IDs and card IDs are different namespaces. Never pass note IDs where card IDs are expected.

• Deck names: Use :: for hierarchy. Double-quotes in deck names must be escaped (\").

• Search syntax: Anki browser syntax — is:due, is:new, prop:due<0 (overdue), deck:"Name", tag:foo, nid:123.

• Error handling: All AnkiConnect failures throw AnkiConnectError(action, message). MCP SDK surfaces these to the client as tool errors.

Architecture

src/
  ankiconnect.ts      — HTTP client, branded ID types, AnkiConnectError
  tools/
    notes.ts          — create / search / update / delete / move notes + tag management
    decks.ts          — create / list / delete decks
    study.ts          — get due cards / submit answer / reschedule / suspend / forget
    insights.ts       — retention stats
  index.ts            — McpServer wiring (registerTool), stdio transport

Performance notes

• search_notes: always pass a narrow query + explicit limit to avoid large payloads.

• get_insights on large collections calls cardsInfo in 500-card chunks sequentially; expect ~1s per 500 cards.

• get_insights without a deck argument fans out cardReviews to every deck — adds one request per deck.

License

MIT