Skip to main content
Glama

anki-mcp-server

An MCP server that lets Claude (or any MCP client) work with your Anki flashcards. It can create decks, add notes, import TSV/CSV files, search, edit, move, rename and delete, add pronunciation audio, and sync to AnkiWeb so changes reach AnkiDroid / AnkiMobile.

"Create a deck Spanish::Verbs and add these 10 verbs with example sentences." "Import ~/Downloads/spanish.csv into my Spanish deck. Do a dry run first." "Add Spanish pronunciation audio to the notes I added today, then sync." "Find every card tagged verbs that has no example sentence." "Move all notes tagged grammar into Spanish::Grammar."

It works on macOS, Windows and Linux, with Anki Desktop and the free AnkiConnect add-on.


Install

1. Install Anki Desktop (once)

Download it from https://apps.ankiweb.net, install it, and open it once: its first window asks for a language and creates your profile.

  • macOS: open the .dmg and drag Anki to Applications. With Homebrew: brew install --cask anki.

  • Windows: run the installer (anki-…-windows.exe).

  • Linux: use the official package from the download page, or Flatpak: flatpak install flathub net.ankiweb.Anki.

Anki 23.10 or newer is required.

Phone: to get your cards on your phone, create a free AnkiWeb account, click Sync in Anki, and sign in to AnkiDroid (Android) or AnkiMobile (iPhone) with the same account.

2. Connect it to Claude: pick one

You use

Easiest option

Claude Desktop (chat)

A. Desktop extension: one click, nothing else to install

Claude Code or Cowork

B. Plugin

Not sure, or you want everything set up for you

C. One-line installer

Use only one of A and C for Claude Desktop; otherwise Claude sees the tools twice.

A. Claude Desktop extension (one click)

  1. AnkiConnect: in Anki choose Tools → Add-ons → Get Add-ons…, enter 2055492159, click OK, then restart Anki.

  2. Download anki-mcp-server.mcpb from the latest release.

  3. Double-click it, or in Claude Desktop go to Settings → Extensions → Advanced settings → Install Extension…, then click Install.

Claude Desktop takes care of Python and everything else. In the extension's settings you can turn on read-only mode or turn off deleting.

B. Claude Code / Cowork plugin

  • Claude Code: run these two commands in a session:

    /plugin marketplace add MeisamHakimi/anki-mcp-server
    /plugin install anki-flashcards@meisamhakimi
  • Claude app (Cowork): go to Customize → Plugins → Add → Add marketplace, enter MeisamHakimi/anki-mcp-server, then add Anki Flashcards (community).

The plugin adds the server and a skill that teaches Claude good Anki habits: dry runs first, and your approval before any change. It needs uv and AnkiConnect. After installing uv, run uvx anki-mcp-server setup --skip-claude to check Anki and install AnkiConnect. The server runs on your computer, so the plugin works in Claude Code and in Cowork sessions on your computer, not in regular claude.ai chat (use option A for that).

C. One-line installer (sets up everything)

macOS / Linux (Terminal):

curl -LsSf https://raw.githubusercontent.com/MeisamHakimi/anki-mcp-server/main/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/MeisamHakimi/anki-mcp-server/main/install.ps1 | iex"

The installer:

  1. installs uv if it's missing. uv brings its own Python, so you don't need Python or git.

  2. starts the setup wizard, which asks before every change:

    • checks that Anki is installed (and offers to install it with Homebrew/Flatpak, or opens the download page),

    • installs the AnkiConnect add-on from AnkiWeb (the same download Anki's Get Add-ons uses, verified before installing),

    • optionally installs the Anki MCP Bridge add-on (recommended if you use AwesomeTTS),

    • restarts Anki and checks the connection,

    • adds the server to Claude Desktop (backing up your config; an existing anki entry is never replaced without asking) and to Claude Code if it's installed.

Add --dry-run to see what it would do without changing anything (… | sh -s -- --dry-run). To read the scripts first, see install.sh and install.ps1.

3. Try it

Restart Claude Desktop completely (⌘Q on Mac, File → Exit on Windows) after options A or C. Then say "Check my Anki status."

You don't need to open Anki first: if it isn't running, the server starts it in the background. Claude asks permission the first time it uses each tool.

Manual setup

  1. AnkiConnect: in Anki choose Tools → Add-ons → Get Add-ons…, enter 2055492159, click OK, then restart Anki.

  2. uv: run curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows). Then find the full path of uvx with which uvx (macOS/Linux) or where uvx (Windows).

  3. Claude Desktop: go to Settings → Developer → Edit Config, add the following inside the top-level { }, save, and fully restart Claude. Use the full uvx path: desktop apps often can't see your terminal's PATH.

    "mcpServers": {
      "anki": {
        "command": "/Users/<you>/.local/bin/uvx",
        "args": ["anki-mcp-server"]
      }
    }

    If "mcpServers" already exists, add just the "anki": {…} part inside it.

  4. Claude Code:

    claude mcp add anki --scope user -- uvx anki-mcp-server
  5. Other MCP clients: run uvx anki-mcp-server (or pip install anki-mcp-server, then run anki-mcp-server) as a stdio server.

macOS tip: if Anki responds slowly while it's in the background, run this once and restart Anki:

defaults write net.ankiweb.dtop NSAppSleepDisabled -bool true

Updating

  • Desktop extension: download the newer .mcpb from Releases and install it again.

  • Plugin: updates arrive automatically from the marketplace.

  • Installer: run it again, then restart Claude.


Related MCP server: AnkiMCP Server

Pronunciation audio (text-to-speech)

Audio works out of the box:

"Add audio of the Word field into the Audio field for deck:"English" notes." "Add Spanish audio (lang es) of the Front field into the Back field for notes added today."

  • Built-in engine (default): free Google Translate voices in 60+ languages (lang: en, es, fr, de, ja, zh-CN, …) and English accents (accent: com US, co.uk, com.au, ca, co.in). No add-on or API key is needed. It needs internet, and the text being spoken is sent to Google.

  • AwesomeTTS: if you use the AwesomeTTS add-on and install the bridge add-on (below), audio uses your AwesomeTTS voice and presets automatically.

  • Nothing is overwritten: only notes whose audio field is empty get audio. Use dry_run to preview.

Audio is stored as [sound:…] in the field you choose. If your note type has no audio field, use an existing one (e.g. Back), or add a field in Anki via Tools → Manage Note Types → Fields.

Optional: the Anki MCP Bridge add-on

Everything works without it. The bridge adds three things AnkiConnect can't do:

  • Rename your Anki profile (e.g. "User 1" → your name)

  • Exact deck renames, which keep the deck description and allow capitalization-only changes. Without the bridge, renames move the cards to a newly named deck, which keeps the cards, review history and options.

  • Use your AwesomeTTS voice

Install: say yes when the installer offers it, or ask Claude "Install the Anki MCP bridge". Then restart Anki.

It listens on 127.0.0.1:8766 only, refuses requests from web browsers, and never returns AwesomeTTS settings or API keys. AwesomeTTS support relies on AwesomeTTS internals (tested with 1.89.4), so an AwesomeTTS update could break only that feature.


Safety

Your collection is personal data you've built over years, so this server is cautious by default:

  • Local connections only. It uses the stdio transport (no network listener) and only talks to Anki on 127.0.0.1; other URLs are rejected. The one exception is built-in TTS, which sends the spoken text to Google (see Privacy Policy).

  • Adding never overwrites. Notes are added with allowDuplicate=false; duplicates are reported back as skipped. dry_run previews adds, imports and audio.

  • Changes and deletions are two-step. A tool that edits, moves, renames or deletes first returns a preview and a confirm_token, without changing anything. The change only runs when the tool is called again with that token. The token is rejected if the arguments differ, if the notes changed since the preview, or if the server restarted. The server tells the model to get your explicit approval first.

  • Backups before every change go to ~/.anki-mcp-server/backups/: affected notes as JSON, and deleted decks as an .apkg with review history (restore it via Anki → File → Import). AnkiConnect edits bypass Anki's undo, so these backups are your undo. Anki's own automatic backups (File → Switch Profile → Open Backup) are another safety net.

  • Allowlisted actions. Only the AnkiConnect actions this server needs are used. Note-type, template and deck-option editing are never exposed.

  • Modes. ANKI_MCP_READ_ONLY=1 exposes only read tools. ANKI_MCP_ALLOW_DELETE=0 hides the delete tools.

  • Tool annotations. Every tool is marked read-only or destructive, so MCP clients can ask for confirmation appropriately.

Tools

Tool

Kind

What it does

anki_status

read

AnkiConnect version, profile, decks, note types and their fields, available features

anki_find_notes

read

Anki search syntax → notes with fields, tags and decks

anki_list_tags

read

All tags

anki_open_browser

read

Opens Anki's Browse window filtered by a search

anki_tts_status

read

Available audio engines, languages and AwesomeTTS presets

anki_create_deck

add

Creates a deck (Parent::Child for subdecks); a no-op if it exists

anki_add_notes

add

Adds notes; duplicates skipped; dry_run

anki_import_file

add

Imports .txt/.tsv/.csv: header or columns mapping, a tags column, tag_rules, Anki plain-text exports, dry_run

anki_generate_audio

add

Text-to-speech into empty audio fields (Google built-in or AwesomeTTS)

anki_sync

add

Syncs with AnkiWeb

anki_update_notes

change

Edits fields and tags (preview → confirm, backup)

anki_move_notes

change

Moves notes to another deck (preview → confirm, backup)

anki_rename_deck

change

Renames a deck and its subdecks (preview → confirm)

anki_rename_profile

change

Renames the Anki profile (preview → confirm; bridge)

anki_install_bridge

change

Installs or updates the bridge add-on (preview → confirm)

anki_delete_notes

delete

Deletes notes (preview → confirm, JSON backup)

anki_delete_deck

delete

Deletes a deck and its cards (preview → confirm, .apkg + JSON backup)

Note types and field names

You can use friendly field names. Matching is case-insensitive, and a unique prefix works: "example" maps to a field called Example sentence. If you don't pass model, adds and imports use ANKI_DEFAULT_MODEL, else the note type most used in the target deck, else Anki's standard Basic (Front/Back).

Importing files

word	meaning	example
resilient	able to recover quickly	She is remarkably resilient.
GRAMMAR NOTE: present perfect	have/has + past participle	I have lived here for years.

"Import ~/vocab.txt into English::Vocabulary. Tag rows whose word starts with GRAMMAR NOTE: as grammar and everything else as vocab."

This becomes:

{"path": "~/vocab.txt", "deck": "English::Vocabulary",
 "tag_rules": [{"field": "Word", "starts_with": "GRAMMAR NOTE:", "tag": "grammar"}],
 "default_tag": "vocab", "dry_run": true}
  • Delimiter: tab, comma, semicolon or pipe, auto-detected. Tab-separated files are read literally; other delimiters follow CSV quoting rules. Files must be UTF-8.

  • Columns: taken from a header row if there is one (auto-detected when it matches field names), else from columns, else in the note type's field order. Use "" to skip a column and "tags" for a space-separated tags column.

  • Anki exports: "Notes in Plain Text" exports work, including their #separator: and #columns: lines.

  • Tag rules: each rule needs field, tag, and one of starts_with, contains or regex. They're case-insensitive unless you set "case_sensitive": true.

Configuration (optional)

Set these in the env block of your MCP config.

Variable

Default

Meaning

ANKI_CONNECT_URL

http://127.0.0.1:8765

AnkiConnect address (must be localhost)

ANKI_CONNECT_API_KEY

–

Set this if you configured apiKey in AnkiConnect

ANKI_MCP_BRIDGE_URL

http://127.0.0.1:8766

Bridge add-on address (must be localhost)

ANKI_AUTO_LAUNCH

1

Start Anki if it isn't running

ANKI_LAUNCH_COMMAND

per OS

Custom command to start Anki, e.g. flatpak run net.ankiweb.Anki

ANKI_BASE

per OS

Anki's data folder, used to install the bridge (Anki: Tools → Add-ons → View Files, one level up)

ANKI_MCP_BACKUP_DIR

~/.anki-mcp-server/backups

Where backups go

ANKI_DEFAULT_MODEL

–

Default note type for adds/imports

ANKI_MCP_READ_ONLY

0

1 = read tools only

ANKI_MCP_ALLOW_DELETE

1

0 = hide the delete tools

"anki": {
  "command": "/Users/<you>/.local/bin/uvx",
  "args": ["anki-mcp-server"],
  "env": { "ANKI_MCP_ALLOW_DELETE": "0" }
}

Troubleshooting

Problem

Fix

Claude doesn't list the anki tools

Fully quit and reopen Claude. Run the installer again (it fixes the config), or check that the config uses the full path to uvx. Claude Desktop → Settings → Developer shows the server's error.

"Can't connect to AnkiConnect"

Run the installer again, or install AnkiConnect manually and restart Anki. To check, run curl -s localhost:8765 -X POST -d '{"action":"version","version":6}'; it should print {"result": 6, ...}.

"Anki isn't installed / couldn't be found"

Install Anki (step 1) and open it once. For a non-standard install, set ANKI_LAUNCH_COMMAND.

"Started Anki, but AnkiConnect didn't answer"

Anki is waiting at the profile picker or a dialog; check its window. Otherwise AnkiConnect isn't installed.

Slow or timing out on macOS

Run the App Nap command from Manual setup, then restart Anki.

Audio fails

Built-in audio needs internet. If several requests fail, Google may be rate-limiting; try again later or with a smaller limit.

An edit shows not_applied

The note was open in Anki's editor or Browse window. Close it and retry.

"needs the Anki MCP Bridge add-on"

Ask Claude to install the bridge, then restart Anki.

Restoring something

Decks: import the .apkg from the backup folder (File → Import). Notes: the JSON backups contain every field and tag. Whole collection: Anki's File → Switch Profile → Open Backup.

Development

git clone https://github.com/MeisamHakimi/anki-mcp-server && cd anki-mcp-server
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                 # tests use fake AnkiConnect and bridge servers; Anki isn't needed
python scripts/build_addon.py    # builds dist/anki_mcp_bridge.ankiaddon
python scripts/build_mcpb.py     # builds dist/anki-mcp-server.mcpb (needs Node.js)
claude plugin validate ./plugins/anki-flashcards   # checks the Claude plugin
.venv/bin/anki-mcp-server setup --dry-run   # try the setup wizard without changing anything
npx @modelcontextprotocol/inspector .venv/bin/anki-mcp-server   # try the tools interactively

Privacy Policy

anki-mcp-server runs entirely on your computer. The author collects no data and runs no servers, and there is no telemetry.

  • Your notes are read and changed locally through Anki/AnkiConnect on 127.0.0.1. Tool results go to the AI app you use (e.g. Claude) under that app's privacy policy.

  • Third parties, only when you use these features:

    • Google receives the text being spoken by the built-in text-to-speech.

    • AnkiWeb receives your collection when you sync, through Anki itself.

    • AnkiWeb, PyPI, GitHub and astral.sh serve the downloads during installation; these requests contain no personal data.

  • Retention: backups stay in ~/.anki-mcp-server/backups/ on your computer until you delete them. Nothing is kept by the author.

  • Contact: GitHub issues, or private reports through security advisories.

Full policy: PRIVACY.md. Security policy: SECURITY.md.

License

MIT. This is an unofficial community project, not affiliated with or endorsed by Anki/Ankitects, AnkiConnect, AwesomeTTS, Google or Anthropic.

Available Tools

17 tools
anki_add_notesAdd notesA
Idempotent

Add notes to an existing deck. Existing notes are never overwritten; duplicates are skipped and reported.

notes: list of {field: value}, e.g. [{"Front": "hola", "Back": "hello"}]. Field names are matched to the note type case-insensitively, and a unique prefix works ("Example" -> "Example sentence"). model: note type. Default: ANKI_DEFAULT_MODEL, else the note type most used in that deck. tags: tags for every note. duplicate_scope: "collection" (Anki's default: same first field + same note type anywhere) or "deck". allow_html: if false (default), text is HTML-escaped and newlines become . dry_run: report what would be added/skipped without writing.

Inputs: deck (required), notes (required), tags, model, +3 more. Returns: object

anki_create_deckCreate deckA
Idempotent

Create a deck. Use "Parent::Child" for subdecks. Does nothing if it already exists.

Inputs: name (required). Returns: object

anki_delete_deckDelete deckA
Destructive

Delete a deck, its subdecks and all their cards. Two-step: preview + token, then call again with confirm_token. The deck is first exported (with review history) to an .apkg in the backup folder, which can be re-imported via Anki's File -> Import.

Inputs: name (required), confirm_token. Returns: object

anki_delete_notesDelete notesA
Destructive

Delete notes with all their cards and review history. Give note_ids OR an Anki search query. Two-step: preview + token, then call again with confirm_token. A JSON backup is written first.

Inputs: query, note_ids, confirm_token. Returns: object

anki_find_notesFind notesA
Read-only

Search notes with Anki search syntax, e.g. 'deck:"Spanish"', 'tag:verbs', 'Front:hola', 'added:1', 'is:due'. Returns each note's id, note type, deck(s), tags and fields.

Inputs: query (required), limit. Returns: object

anki_generate_audioAdd pronunciation audioA
Idempotent

Add text-to-speech audio to notes matching an Anki search (e.g. 'deck:"Spanish" added:1'). Only notes whose dest_field is empty are processed; nothing is overwritten.

source_field: field whose text is spoken. dest_field: field that receives [sound:...] (e.g. "Back" or an "Audio" field). Works out of the box. engine: "google" = built-in, free Google Translate voices, needs internet; the text is sent to Google. "awesometts" = your AwesomeTTS add-on voice (needs AwesomeTTS + the bridge add-on). "auto" (default) = AwesomeTTS if available, else google. lang: language code for google (e.g. "en", "es", "fr", "de", "ja", "zh-CN"); see anki_tts_status. accent: Google domain for regional accents with lang "en": "com" (US), "co.uk", "com.au", "ca", "co.in". preset: AwesomeTTS preset name (or "group:"); default = the voice last used in AwesomeTTS.

Inputs: query (required), dest_field (required), source_field (required), lang, +5 more. Returns: object

anki_import_fileImport notes from fileA
Idempotent

Import a .txt/.tsv/.csv file into an existing deck, one note per row.

Columns map to fields: from columns (e.g. ["Front", "Back", "tags"]; "" skips a column, "tags" means space-separated tags), else from a header row, else in the note type's field order. has_header: None = auto (first row equals field names). Anki "Notes in Plain Text" exports (#separator:/#columns: lines) work. tags: added to every row. tag_rules: per-row tags, e.g. [{"field": "Front", "starts_with": "GRAMMAR:", "tag": "grammar"}] (also "contains" or "regex"; "case_sensitive": false by default). default_tag: tag for rows that match no rule. Duplicate handling, model default and dry_run work like anki_add_notes.

Inputs: deck (required), path (required), tags, model, +8 more. Returns: object

anki_install_bridgeInstall bridge add-onA
Idempotent

Install (or update) the optional Anki MCP Bridge add-on into Anki's add-ons folder. It enables renaming the Anki profile, exact deck renames, and AwesomeTTS audio. Two-step: preview + token. The user must restart Anki afterwards.

Inputs: confirm_token. Returns: object

anki_list_tagsList tagsA
Read-only

List all tags in the collection.

Inputs: no named parameters. Returns: object

anki_move_notesMove notesA
Destructive

Move notes (all their cards, keeping review history) to another existing deck. Give note_ids OR an Anki search query. Two-step: preview + token, then call again with confirm_token.

Inputs: target_deck (required), query, note_ids, confirm_token. Returns: object

anki_open_browserOpen Anki browserA
Read-only

Open Anki's Browse window filtered by an Anki search, so the user can look at or act on those cards.

Inputs: query (required). Returns: object

anki_rename_deckRename deckA
Destructive

Rename a deck (subdecks follow; cards, review history and option presets are kept). "A::B" nests it under A. Two-step: preview + token, then call again with confirm_token. Uses the bridge add-on if installed, otherwise moves the cards to a new deck with the new name.

Inputs: name (required), new_name (required), confirm_token. Returns: object

anki_rename_profileRename profileA
Destructive

Rename the current Anki profile (e.g. the default "User 1"). Anki briefly closes and reopens the collection, like File -> Switch Profile, and syncs if sync-on-open/close is enabled. Cards, history, add-ons and the AnkiWeb login are kept. Two-step: preview + token. Needs the bridge add-on.

Inputs: new_name (required), confirm_token. Returns: object

anki_statusAnki statusA
Read-only

Check the connection. Returns the AnkiConnect version, current profile (if the bridge add-on is installed), decks, note types with their fields, and which optional features are available.

Inputs: no named parameters. Returns: object

anki_syncSync with AnkiWebA
Idempotent

Sync the collection with AnkiWeb (requires being logged in to AnkiWeb in Anki).

Inputs: no named parameters. Returns: object

anki_tts_statusText-to-speech statusA
Read-only

Which text-to-speech engines are available: built-in Google voices (with language codes) and, if the AwesomeTTS add-on + bridge are installed, its presets and last used voice (never options or API keys).

Inputs: no named parameters. Returns: object

anki_update_notesEdit notesA
Destructive

Edit existing notes' fields and/or tags. Two-step: without confirm_token it returns a before/after preview and a token; call again with the same arguments + confirm_token to apply (notes are backed up first).

updates: [{"note_id": 123, "fields": {"Back": "new text"}, "add_tags": ["x"], "remove_tags": ["y"]}] Only the listed fields change; "" clears a field (except the first field).

Inputs: updates (required), allow_html, confirm_token. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (add/find/update/delete notes, create/rename/delete decks, sync, audio generation). Minor overlaps exist: anki_status and anki_tts_status both report environment features, and anki_add_notes vs anki_import_file both add notes (bulk API vs file), but the descriptions distinguish them adequately. The repeated two-step confirm_token pattern across destructive tools is uniform and predictable.

    Naming Consistency5/5

    Every tool uses the anki_ prefix followed by a snake_case verb_noun (anki_create_deck, anki_find_notes, anki_move_notes, anki_delete_notes). A couple of noun-only names (anki_status, anki_sync) are conventional and readable. No mixing of casing or verb styles anywhere in the set.

    Tool Count4/5

    17 tools is on the heavy side but each covers a distinct operation in the Anki collection lifecycle, and the domain (decks, notes, tags, audio, sync, backups, bridge install) genuinely warrants this breadth. Slightly over the ideal 3-15 range but without obvious padding or redundant tools.

    Completeness4/5

    Strong coverage: notes have find/add/import/update/move/delete with backups and dry-run, decks have create/rename/delete, plus sync, TTS, and bridge install. Gaps are minor but real: no explicit list_decks or create/rename tags tools (tags are only listable, modified indirectly via update_notes), and no card review/study operation beyond search filters like is:due.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants like Claude to interact with Anki flashcard decks through AnkiConnect. Supports creating and managing decks, basic and cloze deletion cards, searching existing cards, and organizing content with tags.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes Anki flashcard collections to AI assistants via MCP, enabling AI-powered study sessions, card creation, deck management, and review workflows. Supports comprehensive collection operations including search, media management, and note type customization.
      102
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides programmatic access to Anki flashcard operations through the AnkiConnect API, allowing users to list and create decks and cards. It enables seamless management of flashcards directly from MCP-compatible clients like Claude Desktop.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to manage Anki flashcards, decks, note types, tags, and media via AnkiConnect. Supports operations like adding, editing, finding, and syncing cards through a local MCP server.
      100
      MIT