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.

Quick start

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. If Anki is missing, the installer below offers to install it with Homebrew/Flatpak, or opens the download page.

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. Run the installer (one line)

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,

   • 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. Restart Claude and try it

Quit Claude Desktop completely (⌘Q on Mac, File → Exit on Windows) and reopen it. 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.

Don't have Claude Desktop yet? Get it at https://claude.ai/download, then run the installer again.

Manual setup (if you prefer not to use the installer)

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": ["--from", "anki-mcp-server @ https://github.com/MeisamHakimi/anki-mcp-server/archive/refs/heads/main.zip", "anki-mcp-server"]
     }
   }

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

4. Claude Code:

   claude mcp add anki --scope user -- uvx --from "anki-mcp-server @ https://github.com/MeisamHakimi/anki-mcp-server/archive/refs/heads/main.zip" anki-mcp-server

5. Other MCP clients: run the same uvx … command (or pip install the zip URL and 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

Run the installer again. It points Claude at the newest release; restart Claude afterwards.

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.

• 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

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.

"anki": {
  "command": "/Users/<you>/.local/bin/uvx",
  "args": ["--from", "anki-mcp-server @ https://github.com/MeisamHakimi/anki-mcp-server/archive/refs/heads/main.zip", "anki-mcp-server"],
  "env": { "ANKI_MCP_ALLOW_DELETE": "0" }
}

Troubleshooting

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
.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

License

MIT. Not affiliated with Anki, AnkiConnect, AwesomeTTS or Google.