anki-mcp-server
Provides tools for managing an Anki flashcard collection through the AnkiConnect add-on: creating decks and subdecks, adding notes (skipping duplicates), importing TSV/CSV/plain-text files, searching notes and tags, editing fields and tags, moving notes between decks, renaming decks and profiles, and deleting notes or decks. Supports pronunciation audio generation into note fields and syncing the collection to AnkiWeb so changes reach AnkiDroid/AnkiMobile. All changes and deletions are two-step (preview then confirm) with automatic backups.
Used as the built-in text-to-speech engine for adding pronunciation audio to Anki notes, offering free Google Translate voices in 60+ languages and several English accents, stored as [sound:…] in the chosen note field. Requires internet and sends the spoken text to Google.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@anki-mcp-server Create a deck Spanish::Verbs and add these 10 verbs with example sentences."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.csvinto my Spanish deck. Do a dry run first." "Add Spanish pronunciation audio to the notes I added today, then sync." "Find every card taggedverbsthat has no example sentence." "Move all notes taggedgrammarinto 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
.dmgand 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 | |
Not sure, or you want everything set up for you |
Use only one of A and C for Claude Desktop; otherwise Claude sees the tools twice.
A. Claude Desktop extension (one click)
AnkiConnect: in Anki choose Tools → Add-ons → Get Add-ons…, enter
2055492159, click OK, then restart Anki.Download anki-mcp-server.mcpb from the latest release.
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@meisamhakimiClaude 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 | shWindows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/MeisamHakimi/anki-mcp-server/main/install.ps1 | iex"The installer:
installs uv if it's missing. uv brings its own Python, so you don't need Python or git.
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
ankientry 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
AnkiConnect: in Anki choose Tools → Add-ons → Get Add-ons…, enter
2055492159, click OK, then restart Anki.uv: run
curl -LsSf https://astral.sh/uv/install.sh | sh(macOS/Linux) orpowershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"(Windows). Then find the full path of uvx withwhich uvx(macOS/Linux) orwhere uvx(Windows).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.Claude Code:
claude mcp add anki --scope user -- uvx anki-mcp-serverOther MCP clients: run
uvx anki-mcp-server(orpip install anki-mcp-server, then runanki-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 trueUpdating
Desktop extension: download the newer
.mcpbfrom 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:comUS,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_runto 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_runpreviews 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.apkgwith 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=1exposes only read tools.ANKI_MCP_ALLOW_DELETE=0hides 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 |
| read | AnkiConnect version, profile, decks, note types and their fields, available features |
| read | Anki search syntax → notes with fields, tags and decks |
| read | All tags |
| read | Opens Anki's Browse window filtered by a search |
| read | Available audio engines, languages and AwesomeTTS presets |
| add | Creates a deck ( |
| add | Adds notes; duplicates skipped; |
| add | Imports |
| add | Text-to-speech into empty audio fields (Google built-in or AwesomeTTS) |
| add | Syncs with AnkiWeb |
| change | Edits fields and tags (preview → confirm, backup) |
| change | Moves notes to another deck (preview → confirm, backup) |
| change | Renames a deck and its subdecks (preview → confirm) |
| change | Renames the Anki profile (preview → confirm; bridge) |
| change | Installs or updates the bridge add-on (preview → confirm) |
| delete | Deletes notes (preview → confirm, JSON backup) |
| delete | Deletes a deck and its cards (preview → confirm, |
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.txtintoEnglish::Vocabulary. Tag rows whose word starts withGRAMMAR NOTE:asgrammarand everything else asvocab."
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 ofstarts_with,containsorregex. 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 |
|
| AnkiConnect address (must be localhost) |
| – | Set this if you configured |
|
| Bridge add-on address (must be localhost) |
|
| Start Anki if it isn't running |
| per OS | Custom command to start Anki, e.g. |
| per OS | Anki's data folder, used to install the bridge (Anki: Tools → Add-ons → View Files, one level up) |
|
| Where backups go |
| – | Default note type for adds/imports |
|
|
|
|
|
|
"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 |
"Can't connect to AnkiConnect" | Run the installer again, or install AnkiConnect manually and restart Anki. To check, run |
"Anki isn't installed / couldn't be found" | Install Anki (step 1) and open it once. For a non-standard install, set |
"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 |
An edit shows | 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 |
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 interactivelyPrivacy 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 toolsanki_add_notesAdd notesAIdempotent
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 deckAIdempotent
Create a deck. Use "Parent::Child" for subdecks. Does nothing if it already exists.
Inputs: name (required). Returns: object
anki_delete_deckDelete deckADestructive
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 notesADestructive
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 notesARead-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 audioAIdempotent
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 fileAIdempotent
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-onAIdempotent
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 tagsARead-only
List all tags in the collection.
Inputs: no named parameters. Returns: object
anki_move_notesMove notesADestructive
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 browserARead-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 deckADestructive
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 profileADestructive
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 statusARead-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 AnkiWebAIdempotent
Sync the collection with AnkiWeb (requires being logged in to AnkiWeb in Anki).
Inputs: no named parameters. Returns: object
anki_tts_statusText-to-speech statusARead-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 notesADestructive
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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Turn text, files, URLs, or photos into Anki flashcard decks from your AI assistant.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceExposes 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-
- FlicenseNot gradedqualityDmaintenanceProvides 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.-
- AlicenseBqualityCmaintenanceEnables 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.100MIT