Skip to main content
Glama
Anki Connect MCP Server

Anki Connect MCP Server

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.

Project

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_info

  • Cards: find_cards, cards_info, cards_to_notes, suspend, unsuspend, are_suspended, are_due, get_intervals

  • Decks: deck_names, deck_names_and_ids, get_decks, change_deck, delete_decks, get_deck_config

  • Models: model_names, model_names_and_ids, model_field_names, model_fields_on_templates

  • Misc: version, get_tags

  • Media: 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

ANKI_MCP_ENABLE_GUI=1

gui_browse, gui_add_cards, gui_current_card, gui_start_card_timer, gui_show_question, gui_show_answer, gui_answer_card, gui_deck_overview, gui_deck_browser, gui_deck_review, gui_exit_anki

Advanced

ANKI_MCP_ENABLE_ADVANCED=1

multi, upgrade, save_deck_config, set_deck_config_id, clone_deck_config_id, remove_deck_config_id

Configuration

Variable

Default

Purpose

ANKI_CONNECT_URL

http://localhost:8765

AnkiConnect address

ANKI_CONNECT_API_KEY

–

Sent as key with every request; set it when AnkiConnect has apiKey configured

ANKI_MCP_ENABLE_GUI

off

1 or true enables the GUI tools

ANKI_MCP_ENABLE_ADVANCED

off

1 or true enables the advanced tools

Upgrading from 2.x

  • audio on add_note / add_notes is now an array of { source, filename?, fields[] }; it used to be a single object with url, filename, skipHash and a single fields string.

  • update_note_fields is no longer marked idempotent (idempotentHint: false), because attaching media appends a new tag on every call. Its fields is 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) and get_media_dir_path.

Upgrading from 1.x

  • create_flashcard was removed; use add_note with deckName, modelName and fields.

  • GUI tools, multi, upgrade and 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_cards return { ids, total, truncated } instead of a plain array.

  • Node.js 20 or newer is required.

Prerequisites

1. Install AnkiConnect Add-on

  1. Open Anki

  2. Go to Tools → Add-ons

  3. Click Get Add-ons...

  4. Enter the code: 2055492159

  5. Click OK and restart Anki

2. Configure AnkiConnect (Optional)

AnkiConnect works out of the box, but you can customize its settings:

  1. Go to Tools → Add-ons

  2. Select AnkiConnect and click Config

  3. Modify settings if needed (default port is 8765)

  4. Restart Anki after making changes

Installation

  1. Clone this repository:

git clone https://github.com/spacholski1225/anki-connect-mcp.git
cd anki-connect-mcp
  1. Install dependencies:

npm install
  1. Build the project:

npm run build

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

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.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:

  1. Go to Tools → Add-ons in Anki

  2. Select AnkiConnect and click Config

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

  • Restart Anki after making these configuration changes

Important Notes:

  • For Node.js option: Replace the path in args with the actual path to your built index.js file

  • For npx option: Uses the published NPM package @spacholski1225/anki-connect-mcp - no local installation required

  • For Docker option: Uses the pre-built Docker image spacholski/anki-connect-mcp:latest

  • The alwaysAllow array contains tools that won't require confirmation each time

  • Make sure Anki is running with AnkiConnect enabled before using the MCP server

  • For Docker option, the --network=host flag 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

  1. Connection refused: Make sure Anki is running and AnkiConnect is installed

  2. Port conflicts: Check if port 8765 is available or configure AnkiConnect to use a different port

  3. Permission errors: Ensure the MCP server has proper file system permissions

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

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

License

MIT License

References

Available Tools

33 tools
add_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 notesA
Idempotent

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 dueA
Read-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 suspendedA
Read-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 addedA
Read-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 detailsA
Read-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 IDsA
Read-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 deckA
DestructiveIdempotent

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 decksA
Read-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 IDsA
Read-onlyIdempotent

Returns an object mapping every deck name to its deck ID.

Inputs: no named parameters.

delete_decksDelete decksA
DestructiveIdempotent

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 fileA
DestructiveIdempotent

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 cardsA
Read-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 notesA
Read-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 optionsA
Read-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 cardsA
Read-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 intervalsA
Read-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 pathA
Read-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 filesA
Read-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 tagsA
Read-onlyIdempotent

Returns every tag used in the collection, as an array of strings.

Inputs: no named parameters.

model_field_namesList fields of a note typeA
Read-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 templatesA
Read-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 typesA
Read-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 IDsA
Read-onlyIdempotent

Returns an object mapping every model (note type) name to its model ID.

Inputs: no named parameters.

notes_infoGet note detailsA
Read-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 notesA
DestructiveIdempotent

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 fileA
Read-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 fileA
Idempotent

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 cardsA
Idempotent

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 cardsA
Idempotent

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 fieldsA
Destructive

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 versionA
Read-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

    A3.7/5.0

    Scored across 33 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers