Anki Connect MCP Server
Integrates with Anki via the AnkiConnect add-on to manage flashcards, decks, cards, tags, and GUI operations in Anki.
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 Connect MCP Server Create a new card in my Japanese deck with front '犬' and back 'dog'."
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 Connect MCP Server
A Model Context Protocol (MCP) server that provides seamless integration with Anki through the AnkiConnect add-on. This server enables AI assistants and other MCP clients to interact with your Anki flashcard collection programmatically.

What is Anki Connect?
AnkiConnect is a powerful Anki add-on that exposes Anki's functionality through a REST API. It allows external applications to:
Create, modify, and delete flashcards
Manage decks and their configurations
Control Anki's GUI programmatically
Search and retrieve card information
Manage tags and note types
Perform bulk operations on cards and notes
Related MCP server: Anki MCP Server
What is MCP (Model Context Protocol)?
The Model Context Protocol is a standardized way for AI assistants to connect to external data sources and tools. This MCP server acts as a bridge between MCP clients (like Claude Desktop) and AnkiConnect, allowing AI assistants to help you manage your Anki flashcards naturally through conversation.
Features
Every tool comes with a description, a title and MCP annotations (readOnlyHint / destructiveHint), so clients can auto-approve read-only tools and ask before destructive ones. On connect the server also sends instructions for the agent: Anki search syntax, note IDs vs card IDs, and the recommended flow for adding cards.
Errors are reported as tool errors (isError: true): AnkiConnect error: ... when Anki rejects a request, Could not reach AnkiConnect at <url>... when Anki is not running, and a plain message describing the problem when the arguments are wrong (e.g. an unknown field name).
Default tools
Notes:
add_note,add_notes,can_add_notes,update_note_fields,add_tags,remove_tags,find_notes,notes_infoCards:
find_cards,cards_info,cards_to_notes,suspend,unsuspend,are_suspended,are_due,get_intervalsDecks:
deck_names,deck_names_and_ids,get_decks,change_deck,delete_decks,get_deck_configModels:
model_names,model_names_and_ids,model_field_names,model_fields_on_templatesMisc:
version,get_tagsMedia:
store_media_file,get_media_files_names,retrieve_media_file,delete_media_file,get_media_dir_path
find_notes and find_cards return { ids, total, truncated } and accept an optional limit (default 100); get_media_files_names returns { names, total, truncated } the same way. cards_info strips the card CSS from the question and answer.
Images, audio and video: add_note, add_notes and update_note_fields take picture, audio and video arrays of { source, filename?, fields }. source is an http(s) URL or an absolute path on the computer running Anki (Anki itself downloads or reads it, so a path must exist on that machine), "clipboard" for the image currently copied on the computer running this server (Linux only; needs wl-clipboard on Wayland or xclip on X11), or a base64 data URL (data:image/png;base64,...). Clipboard and data-URL files default to the name pasted-<hash>.<ext>, so the same image is stored once. The file is stored and appended to each listed field. To place an image inside text instead, call store_media_file and write <img src="NAME"> with the returned name; Anki may rename files, so never assume the requested name. If a file cannot be stored, no note is created or changed and the error names the failing item. retrieve_media_file returns PNG, JPEG, GIF and WebP images up to 5 MB as image content the agent can see.
Optional tool groups
Group | Enabled by | Tools |
GUI |
|
|
Advanced |
|
|
Configuration
Variable | Default | Purpose |
|
| AnkiConnect address |
| – | Sent as |
| off |
|
| off |
|
Upgrading from 2.x
audioonadd_note/add_notesis now an array of{ source, filename?, fields[] }; it used to be a single object withurl,filename,skipHashand a singlefieldsstring.update_note_fieldsis no longer marked idempotent (idempotentHint: false), because attaching media appends a new tag on every call. Itsfieldsis now optional.Five media tools are now in the default group:
store_media_file,get_media_files_names,retrieve_media_file,delete_media_file(destructive) andget_media_dir_path.
Upgrading from 1.x
create_flashcardwas removed; useadd_notewithdeckName,modelNameandfields.GUI tools,
multi,upgradeand deck-config editing tools are hidden unless their group is enabled.Tool results contain only AnkiConnect's
result(no{result, error}envelope); errors come back as tool errors.find_notes/find_cardsreturn{ ids, total, truncated }instead of a plain array.Node.js 20 or newer is required.
Prerequisites
1. Install AnkiConnect Add-on
Open Anki
Go to Tools → Add-ons
Click Get Add-ons...
Enter the code:
2055492159Click OK and restart Anki
2. Configure AnkiConnect (Optional)
AnkiConnect works out of the box, but you can customize its settings:
Go to Tools → Add-ons
Select AnkiConnect and click Config
Modify settings if needed (default port is 8765)
Restart Anki after making changes
Installation
Clone this repository:
git clone https://github.com/spacholski1225/anki-connect-mcp.git
cd anki-connect-mcpInstall dependencies:
npm installBuild the project:
npm run buildMCP Client Configuration
Claude Desktop
To use this MCP server with Claude Desktop, add the following configuration to your MCP settings file:
Location of MCP configuration file:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Configuration Options:
Option 1: Using Node.js (Local Installation)
{
"mcpServers": {
"anki-connect-mcp": {
"command": "node",
"args": [
"dist/index.js"
],
"env": {},
"disabled": false,
"alwaysAllow": [
"deck_names",
"cards_info",
"deck_names_and_ids",
"find_notes"
]
}
}
}Option 2: Using npx (NPM Package)
Then configure your MCP client:
{
"mcpServers": {
"anki-connect": {
"command": "npx",
"args": [
"@spacholski1225/anki-connect-mcp"
],
"env": {},
"disabled": false,
"alwaysAllow": [
"deck_names",
"cards_info",
"deck_names_and_ids",
"find_notes"
]
}
}
}Option 3: Using Docker
{
"mcpServers": {
"anki-connect": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--network=host",
"-e", "ANKI_CONNECT_URL=http://host.docker.internal:8765",
"spacholski/anki-connect-mcp:latest"
],
"env": {},
"disabled": false,
"alwaysAllow": [
"deck_names",
"cards_info",
"deck_names_and_ids",
"find_notes"
]
}
}
}Docker-Specific AnkiConnect Configuration:
When using the Docker option, you must configure AnkiConnect with specific settings to allow Docker container access:
Go to Tools → Add-ons in Anki
Select AnkiConnect and click Config
Update the configuration with the following settings:
{
"apiKey": null,
"apiLogPath": null,
"ignoreOriginList": [],
"webBindAddress": "0.0.0.0",
"webBindPort": 8765,
"webCorsOriginList": [
"http://localhost",
"http://host.docker.internal",
"http://host.docker.internal:3000"
]
}Key Docker Configuration Points:
webBindAddress: "0.0.0.0"- Allows AnkiConnect to accept connections from any IP address (required for Docker containers)webCorsOriginList- Must include"http://host.docker.internal"and related origins to allow cross-origin requests from Docker containersRestart Anki after making these configuration changes
Important Notes:
For Node.js option: Replace the path in
argswith the actual path to your builtindex.jsfileFor npx option: Uses the published NPM package
@spacholski1225/anki-connect-mcp- no local installation requiredFor Docker option: Uses the pre-built Docker image
spacholski/anki-connect-mcp:latestThe
alwaysAllowarray contains tools that won't require confirmation each timeMake sure Anki is running with AnkiConnect enabled before using the MCP server
For Docker option, the
--network=hostflag allows the container to access AnkiConnect on the host machine
Usage Examples
Once configured with an MCP client like Claude Desktop, you can interact with your Anki collection naturally:
"Create a flashcard about the capital of France in my Geography deck"
"Show me all my deck names"
"Find all cards tagged with 'vocabulary'"
"Suspend all cards in the 'Difficult Words' deck"
"Open the deck browser in Anki" (needs
ANKI_MCP_ENABLE_GUI=1)
Troubleshooting
Common Issues
Connection refused: Make sure Anki is running and AnkiConnect is installed
Port conflicts: Check if port 8765 is available or configure AnkiConnect to use a different port
Permission errors: Ensure the MCP server has proper file system permissions
Tool not found: Verify the MCP client configuration and restart the client
Development
npm run typecheck # type-check sources and tests
npm test # protocol-level tests against a fake AnkiConnect
npm run buildContributing
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
License
MIT License
References
Available Tools
33 toolsadd_noteAdd noteA
Creates one note in the given deck using the given model (note type) and field values. Anki then generates one or more cards from it. Returns the new note ID. Fails (tool error) if the deck or model does not exist, a field name is wrong, the first field is empty, or the note is a duplicate. Tip: check with can_add_notes first; for several notes prefer add_notes. Attach images/audio/video with picture/audio/video: each item's source is an http(s) URL or an absolute path on the computer running Anki, and the file is appended to the listed fields. Fails before creating anything if a file cannot be stored.
Inputs: fields (required), deckName (required), modelName (required), tags, +3 more.
add_notesAdd notes (batch)A
Creates several notes in one call. Returns an array of new note IDs in the same order as the input; an entry is null if that note could not be created (e.g. duplicate or empty first field). Run can_add_notes first to find out which notes will fail. If any attached file cannot be stored, no note is created and the error names the note (e.g. notes[2].picture[0]).
Inputs: notes (required).
add_tagsAdd tags to notesAIdempotent
Adds tags to notes (takes note IDs, not card IDs). tags is a single space-separated string, e.g. "verbs chapter1". Returns null on success.
Inputs: tags (required), notes (required).
are_dueCheck whether cards are dueARead-onlyIdempotent
Returns an array of booleans (same order as input) telling whether each card is due for review now. Learning cards with an interval over 20 minutes count as not due until that time has passed.
Inputs: cards (required).
are_suspendedCheck whether cards are suspendedARead-onlyIdempotent
Returns an array of booleans (same order as input) telling whether each card is suspended; null for unknown card IDs.
Inputs: cards (required).
can_add_notesCheck notes can be addedARead-onlyIdempotent
Dry run for add_notes: returns an array of booleans (same order as input) telling whether each note could be created. false usually means a duplicate, an empty first field, or an unknown deck/model. Does not change anything.
Inputs: notes (required).
cards_infoGet card detailsARead-onlyIdempotent
Returns details for the given card IDs: cardId, note (note ID), deckName, modelName, fields, rendered question and answer HTML (CSS removed), interval, due, queue, type, reps, lapses and more. Unknown IDs yield empty objects. Keep the ID list short; the output is large.
Inputs: cards (required).
cards_to_notesConvert card IDs to note IDsARead-onlyIdempotent
Returns the unique note IDs that the given cards belong to (one note can have several cards). Use it before note tools such as add_tags or update_note_fields when you only have card IDs.
Inputs: cards (required).
change_deckMove cards to deckADestructiveIdempotent
Moves cards (card IDs, not note IDs) to the given deck; the deck is created if it does not exist. The cards leave their current decks, so the previous placement is lost. Returns null on success.
Inputs: deck (required), cards (required).
deck_namesList decksARead-onlyIdempotent
Returns the names of all decks, including subdecks written as "Parent::Child". Use it to get exact deck names before adding notes or searching with deck:.
Inputs: no named parameters.
deck_names_and_idsList decks with IDsARead-onlyIdempotent
Returns an object mapping every deck name to its deck ID.
Inputs: no named parameters.
delete_decksDelete decksADestructiveIdempotent
Deletes decks by name. WARNING: with cardsToo=true every card in those decks is permanently deleted as well; recent AnkiConnect versions require cardsToo=true and refuse otherwise. Cannot be undone through this API. Confirm with the user before calling. Returns null on success.
Inputs: decks (required), cardsToo.
delete_media_fileDelete media fileADestructiveIdempotent
Moves a file from Anki's media folder to the trash. Cards that still reference it show a broken image or play nothing. Confirm with the user before deleting a file that notes may use. Returns null.
Inputs: filename (required).
find_cardsFind cardsARead-onlyIdempotent
Searches cards with Anki search syntax and returns CARD IDs (use find_notes for note IDs). Returns {"ids": number[], "total": number, "truncated": boolean}: at most limit IDs (default 100), the total number of matches, and whether the list was cut. Narrow the query instead of raising the limit when possible. Pass the IDs to cards_info for details.
Inputs: query (required), limit.
find_notesFind notesARead-onlyIdempotent
Searches notes with Anki search syntax and returns NOTE IDs (use find_cards for card IDs). Returns {"ids": number[], "total": number, "truncated": boolean}: at most limit IDs (default 100), the total number of matches, and whether the list was cut. Narrow the query instead of raising the limit when possible. Pass the IDs to notes_info for details.
Inputs: query (required), limit.
get_deck_configGet deck optionsARead-onlyIdempotent
Returns the options group (configuration) used by the given deck: new card and review limits, learning steps, lapse settings and its config id.
Inputs: deck (required).
get_decksGet decks of cardsARead-onlyIdempotent
Takes card IDs (not note IDs) and returns an object mapping each deck name to the given card IDs that are in it.
Inputs: cards (required).
get_intervalsGet card intervalsARead-onlyIdempotent
Returns review intervals per card (same order as input). Negative values are in seconds, positive values in days. With complete=true returns the full interval history per card as arrays; otherwise only the most recent interval.
Inputs: cards (required), complete.
get_media_dir_pathGet media folder pathARead-onlyIdempotent
Returns the absolute path of Anki's media folder (collection.media) on the computer running Anki.
Inputs: no named parameters.
get_media_files_namesList media filesARead-onlyIdempotent
Lists file names in Anki's media folder matching pattern. Returns {"names": string[], "total": number, "truncated": boolean} with at most limit names (default 100). Use it to check whether a file already exists.
Inputs: limit, pattern.
get_tagsList tagsARead-onlyIdempotent
Returns every tag used in the collection, as an array of strings.
Inputs: no named parameters.
model_field_namesList fields of a note typeARead-onlyIdempotent
Returns the field names of the given model in order, e.g. ["Front", "Back"]. Use these exact names as keys of fields in add_note/add_notes; the first field must not be empty.
Inputs: modelName (required).
model_fields_on_templatesFields used by card templatesARead-onlyIdempotent
Returns, for each card template of the model, which fields appear on the front and back side: {"Card 1": [["Front"], ["Back"]], ...}.
Inputs: modelName (required).
model_namesList note typesARead-onlyIdempotent
Returns the names of all models (note types), e.g. "Basic", "Basic (and reversed card)", "Cloze".
Inputs: no named parameters.
model_names_and_idsList note types with IDsARead-onlyIdempotent
Returns an object mapping every model (note type) name to its model ID.
Inputs: no named parameters.
notes_infoGet note detailsARead-onlyIdempotent
Returns details for the given note IDs: noteId, modelName, tags, fields (value and order per field) and cards (the card IDs generated from each note). Unknown IDs yield empty objects.
Inputs: notes (required).
remove_tagsRemove tags from notesADestructiveIdempotent
Removes tags from notes (takes note IDs, not card IDs). tags is a single space-separated string. Returns null on success.
Inputs: tags (required), notes (required).
retrieve_media_fileGet media fileARead-onlyIdempotent
Returns a file from Anki's media folder. PNG, JPEG, GIF and WebP images up to 5 MB come back as an image you can see; anything else (audio, video, SVG, larger images) returns {"filename", "bytes"}. Fails if the file does not exist.
Inputs: filename (required).
store_media_fileStore media fileAIdempotent
Stores a file in Anki's media folder and returns the name Anki stored it under, which can differ from the requested name. Always use the returned NAME: put <img src="NAME"> (images) or [sound:NAME] (audio/video) into a note field. Never overwrites an existing file. To attach media while creating or updating a note, prefer the picture/audio/video params of add_note, add_notes and update_note_fields. source may be "clipboard" for the image the user just copied or pasted.
Inputs: source (required), filename.
suspendSuspend cardsAIdempotent
Suspends cards so they are not shown in reviews (reversible with unsuspend). Returns true if at least one card was not already suspended, false otherwise.
Inputs: cards (required).
unsuspendUnsuspend cardsAIdempotent
Unsuspends cards so they return to reviews. Returns true if at least one card was suspended before, false otherwise.
Inputs: cards (required).
update_note_fieldsUpdate note fieldsADestructive
Overwrites the given fields of an existing note (takes a note ID, not a card ID). Fields not listed are left unchanged. The previous values are lost, so read the note with notes_info first if you need them. Returns null on success. Media in picture/audio/video is appended to the field's new value, or to its current value if the field is not being overwritten.
Inputs: id (required), audio, video, fields, +1 more.
versionAnkiConnect versionARead-onlyIdempotent
Returns the AnkiConnect API version number (e.g. 6). Cheap way to check that Anki is running and reachable.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
The notes-vs-cards split is explicitly flagged in nearly every relevant description (find_notes/find_cards, notes_info/cards_info, cards_to_notes), which heads off the biggest confusion risk. A few near-duplicate pairs remain (deck_names vs deck_names_and_ids, model_names vs model_names_and_ids), and get_decks misleadingly takes card IDs rather than returning decks, but descriptions disambiguate them.
Conventions are mixed: verb_noun (get_tags, add_note, delete_decks, find_cards), bare noun phrases (deck_names, model_names, version, notes_info, cards_info), and bare verbs (suspend, unsuspend). The get_ prefix is applied inconsistently (get_tags but not deck_names) and get_decks is semantically misleading, though all names stay snake_case and readable.
33 tools is heavy; the domain is genuinely broad (decks, note types, notes, cards, media, scheduling), but several slots are consolitable duplicates such as deck_names/deck_names_and_ids and model_names/model_names_and_ids that could be one parameterized call. It sits at the upper edge of practical for an agent to scan.
Strong read/create/update coverage for notes, tags, cards, media and decks, but there is no note deletion tool and no way to grade/answer a card or set due dates, so the review lifecycle and cleanup are dead ends. Deck config is readable but not writable, and deck creation only happens implicitly via change_deck.
Maintenance
Related MCP Connectors
Turn text, files, URLs, or photos into Anki flashcard decks from your AI assistant.
Build and study spaced-repetition flashcards with your agent.
Language flashcards in your AI assistant: build decks, edit cards and review what's due in the chat.
Lets Claude, ChatGPT, and Muse read and update your beckett tasks, notes, calendar, and lists.
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.-
- AlicenseNot gradedqualityDmaintenanceEnables interaction with the Anki desktop flashcard application through the Anki-Connect plugin. Supports managing decks, cards, notes, and models, allowing AI assistants to create and query flashcards through natural language.8 npm1ISC
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Anki flashcard collections by creating, searching, and updating cards through a standardized interface. It supports media handling, batch operations, and review scheduling via the AnkiConnect add-on.62MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to interact with Anki via AnkiConnect for creating, searching, and managing flashcards, decks, and note types.1MIT