greycodee/anki-mcp-server

Anki MCP Server

Overview

This project provides a Model Context Protocol (MCP) server that acts as a bridge to the Anki spaced repetition software via the Anki-Connect add-on. It allows MCP-compatible clients (like AI assistants or other applications) to interact with your Anki collection, managing decks, cards, and notes.

Features

• Exposes a comprehensive set of Anki actions as MCP tools.
• Manages communication with the local Anki-Connect instance.
• Provides tools for:
  • Deck Management (list, create, delete, move cards, get stats)
  • Card Management (find, get info, suspend, unsuspend, check status, forget, relearn)
  • Note Management (add, update, find, get info, manage tags, delete)
  • Model Management (list names, list fields)
  • Miscellaneous Actions (request permission, get version, sync)

Prerequisites

1. Anki: You must have Anki installed and running on your system.
2. Anki-Connect Add-on: The Anki-Connect add-on must be installed in Anki and running. By default, it listens on http://127.0.0.1:8765.
3. Python: A compatible Python version (see pyproject.toml).
4. uv: Recommended for managing Python environments and dependencies (uv installation).

Installation

1. Clone the repository:

   git clone <repository-url> # Replace with the actual URL if applicable
   cd anki-mcp-server
   

2. Install dependencies:

   uv sync
   

Running the Server

Ensure Anki is running with the Anki-Connect add-on enabled before starting the server.

You can run the server in several ways:

1. Direct Execution (using uv):

   uv run python main.py
   

   This will start the server using the stdio transport, suitable for direct integration or testing.

2. Development Mode (using MCP Inspector):

   uv run mcp dev main.py
   

   This starts the server and opens the MCP Inspector tool, allowing you to interactively test the available tools and resources.

3. Install for Claude Desktop:

   uv run mcp install main.py --name "Anki Bridge"
   

   This installs the server into Claude Desktop (if available), making the Anki tools accessible within the assistant.

Usage

Once the server is running and connected to an MCP client (like Claude Desktop via mcp install or another application using the MCP protocol):

1. Request Permission: The first action should typically be anki_request_permission. If the client's origin isn't trusted by Anki-Connect, a confirmation popup will appear in Anki.
2. Use Tools: Call the available tools (listed below) to interact with your Anki collection.

Configuration

• Anki-Connect URL: The server connects to Anki-Connect using the URL defined by the ANKICONNECT_URL constant in main.py (default: http://127.0.0.1:8765). Modify this if your Anki-Connect setup uses a different address or port.

Available Tools

The server exposes the following tools, mirroring the Anki-Connect API actions:

Deck Actions

• anki_deck_names: Gets the complete list of deck names.
• anki_deck_names_and_ids: Gets deck names and their IDs.
• anki_create_deck(deck_name: str): Creates a new empty deck.
• anki_change_deck(card_ids: List[int], deck_name: str): Moves cards to a different deck.
• anki_delete_decks(deck_names: List[str]): Deletes specified decks and their cards.
• anki_get_deck_stats(deck_names: List[str]): Gets statistics for specified decks.

Card Actions

• anki_find_cards(query: str): Finds cards using an Anki search query.
• anki_cards_info(card_ids: List[int]): Gets detailed information about multiple cards.
• anki_cards_to_notes(card_ids: List[int]): Gets the note IDs for given card IDs.
• anki_suspend_cards(card_ids: List[int]): Suspends specified cards.
• anki_unsuspend_cards(card_ids: List[int]): Unsuspends specified cards.
• anki_are_suspended(card_ids: List[int]): Checks if cards are suspended.
• anki_are_due(card_ids: List[int]): Checks if cards are due for review.
• anki_forget_cards(card_ids: List[int]): Resets specified cards to new.
• anki_relearn_cards(card_ids: List[int]): Puts specified cards into the relearning state.

Note Actions

• anki_add_note(...): Creates a new Anki note with specified deck, model, fields, options, tags, and media.
• anki_update_note_fields(...): Modifies the fields and media of an existing note.
• anki_find_notes(query: str): Finds notes using an Anki search query.
• anki_notes_info(note_ids: List[int]): Gets detailed information about multiple notes.
• anki_get_note_tags(note_id: int): Gets the tags for a specific note.
• anki_add_tags(note_ids: List[int], tags: str): Adds space-separated tags to notes.
• anki_remove_tags(note_ids: List[int], tags: str): Removes space-separated tags from notes.
• anki_update_note_tags(note_id: int, tags: List[str]): Sets the tags for a note, replacing old ones.
• anki_delete_notes(note_ids: List[int]): Deletes specified notes and their cards.

Model Actions

• anki_model_names(): Gets the list of model (note type) names.
• anki_model_field_names(model_name: str): Gets the list of field names for a given model.

Miscellaneous Actions

• anki_request_permission(): Requests permission to use the Anki-Connect API. Should be called first.
• anki_version(): Gets the version of the Anki-Connect API.
• anki_sync(): Synchronizes the local Anki collection with AnkiWeb.

Contributing

Contributions are welcome! Please refer to the project's contribution guidelines (if available).

License

Specify the license under which this project is distributed (e.g., MIT License).