anki-mcp

An MCP server that exposes your local Anki collection to MCP clients such as Claude Desktop and VS Code, through the AnkiConnect add-on.

Note fields are HTML and are passed through verbatim, so cards can be generated with cloze deletions, bold/italic, and highlight.js-styled code blocks.

Tools

Read

• anki_check_connection — verify Anki is running and AnkiConnect is reachable
• anki_list_decks — every deck (:: denotes nesting)
• anki_list_models — every note type
• anki_get_model_fields — a note type's field names, in template order
• anki_find_notes — note ids matching an Anki search query
• anki_get_notes_info — full note details: model, tags, fields, cards

Write

• anki_create_deck — create a deck, including missing parents
• anki_add_note — add one note (fields are HTML, sent unescaped)
• anki_add_notes — add a batch sharing one deck and note type
• anki_update_note_fields — overwrite fields of an existing note
• anki_sync — sync the collection with AnkiWeb

Requirements

• uv
• Anki, running — the server talks to the live application, not the collection file
• The AnkiConnect add-on: Anki → Tools → Add-ons → Get Add-ons → code 2055492159, then restart Anki

Setup

uv sync
cp .env.example .env

.env (all optional — the defaults work for a standard local Anki):

ANKI_CONNECT_URL=http://localhost:8765
ANKI_TIMEOUT=30

Run it:

uv run anki-mcp

Check it can reach Anki:

uv run python scripts/smoke_client.py

Use with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/anki-mcp", "anki-mcp"]
    }
  }
}

No secrets to pass — AnkiConnect is unauthenticated and local.

Remote (HTTP) hosting

Set MCP_TRANSPORT=http to serve over streamable-http (endpoint /mcp):

MCP_TRANSPORT=http HOST=0.0.0.0 PORT=8000 uv run anki-mcp

This is of limited use here. AnkiConnect binds to localhost on the machine where Anki runs, so a remotely hosted instance of this server has nothing to connect to — every tool would fail. The transport toggle exists for structural parity with a normal MCP server; making it genuinely useful would need a tunnel back to the desktop (a WebSocket relay or similar), which is out of scope. Run it locally over stdio.

Conventions

• Fields are HTML. Values in fields are sent to Anki byte for byte — no escaping, no sanitizing. "<b>x</b>" renders as a bold x; to show a literal <, send <.
• Cloze deletions use {{c1::...}} and require a cloze note type; the syntax is inert on "Basic".
• Field names are case- and space-sensitive ("Back Extra"). Check them with anki_get_model_fields before adding notes.
• Duplicates: anki_add_note fails on a duplicate first field; anki_add_notes skips the offending note and reports its index. Both accept allow_duplicate=True.
• anki_update_note_fields silently does nothing if the note is open in Anki's Browse window — Anki refuses the edit but reports success. Close the browser and retry.
• Tool output is Markdown by default; pass response_format="json" for the raw payload (and for untruncated field HTML).
• Anki must stay open, and it stops serving requests while a modal dialog is up.

Development

uv sync --extra dev
uv run pytest          # tests (HTTP mocked, no network, no real Anki)
uv run ruff check .    # lint
uv run ruff check --fix .
uv run fastmcp inspect src/anki_mcp/server.py:mcp

Security

AnkiConnect has no authentication: anything that can reach port 8765 can read and modify your collection. That is acceptable because it listens on localhost only — do not expose that port, and do not run this server on an untrusted machine. .env is gitignored, though it holds no secrets by default.

This server can create, overwrite, and sync notes. Back up your collection (Anki → File → Export) before letting an agent make bulk changes.

License

MIT