Anki MCP

1# anki-mcp
2 
3A Model Context Protocol (MCP) server for interacting with Anki flashcards via the AnkiConnect add-on. This server exposes AnkiConnect actions as MCP tools, organized into logical services.
4 
5## Prerequisites
6 
7- Anki desktop application
8- AnkiConnect add-on installed and configured in Anki
9- Python 3.8+
10- `uv` (for running and installing dependencies, optional but recommended)
11 
12## Installation
13 
14```bash
15# Clone the repository
16git clone https://github.com/ujisati/anki-mcp.git
17cd anki-mcp
18 
19# Install dependencies (using uv)
20uv pip install -e .
21```
22 
23## Usage
24 
25To run the MCP server:
26 
27```bash
28uv run anki-mcp
29```
30 
31The server will start and listen for MCP requests, typically interfacing with AnkiConnect at `http://127.0.0.1:8765`.
32 
33### Inspecting the Server
34 
35You can use the MCP Inspector to view the available tools:
36 
37```bash
38npx @modelcontextprotocol/inspector uv run anki-mcp
39```
40 
41## Configuration for MCP Clients
42 
43If you're integrating this with an MCP client (like an AI assistant framework), you'll need to configure it to find this server. Here's an example configuration snippet:
44 
45```json
46{
47    "mcpServers": {
48        "anki": {
49            "command": "uv",
50            "args": [
51                "run", // uv will find anki-mcp if run from project root
52                "anki-mcp"
53            ],
54            // If running from outside the project directory, specify the path:
55            // "args": [
56            //     "--directory",
57            //     "/ABSOLUTE/PATH/TO/anki-mcp", // Replace with actual path
58            //     "run",
59            //     "anki-mcp"
60            // ]
61        }
62    }
63}
64```
65 
66## Available MCP Tools
67 
68This MCP server provides access to Anki functionality through tools grouped by services. The tool names correspond directly to AnkiConnect actions.
69 
70### Deck Service (`deck.*`)
71- **`deck.deckNamesAndIds`**: Gets the complete list of deck names and their respective IDs.
72- **`deck.getDeckConfig`**: Gets the configuration group object for a given deck name.
73- **`deck.deckNames`**: Gets the complete list of deck names for the current user.
74- **`deck.createDeck`**: Creates a new empty deck.
75- **`deck.deleteDecks`**: Deletes specified decks.
76- **`deck.changeDeck`**: Moves cards to a different deck.
77- **`deck.saveDeckConfig`**: Saves a deck configuration group.
78 
79### Note Service (`note.*`)
80- **`note.findNotes`**: Returns note IDs for a given Anki search query.
81- **`note.notesInfo`**: Returns information for specified note IDs.
82- **`note.getNoteTags`**: Gets the tags for a specific note ID.
83- **`note.addNote`**: Creates a new note.
84- **`note.updateNoteFields`**: Modifies the fields of an existing note.
85- **`note.deleteNotes`**: Deletes specified notes.
86- **`note.addNotes`**: Creates multiple notes.
87- **`note.addTags`**: Adds tags to specified notes.
88- **`note.removeTags`**: Removes tags from specified notes.
89- **`note.updateNote`**: Modifies the fields and/or tags of an existing note.
90 
91### Card Service (`card.*`)
92- **`card.findCards`**: Returns card IDs for a given Anki search query.
93- **`card.cardsInfo`**: Returns information for specified card IDs.
94- **`card.cardsToNotes`**: Returns note IDs for given card IDs.
95- **`card.areSuspended`**: Checks if specified cards are suspended.
96- **`card.cardsModTime`**: Returns modification time for specified card IDs.
97- **`card.suspended`**: Checks if a single card is suspended.
98- **`card.suspend`**: Suspends specified cards.
99- **`card.unsuspend`**: Unsuspends specified cards.
100- **`card.setSpecificValueOfCard`**: Sets specific values of a single card (use with caution).
101 
102### Model Service (`model.*`) (Note Types)
103- **`model.modelNamesAndIds`**: Gets the complete list of model (note type) names and their IDs.
104- **`model.findModelsByName`**: Gets model definitions for provided model names.
105- **`model.modelFieldNames`**: Gets field names for a given model name.
106- **`model.modelTemplates`**: Gets template content for each card of a specified model.
107- **`model.modelStyling`**: Gets CSS styling for a given model name.
108- **`model.createModel`**: Creates a new model (note type).
109- **`model.updateModelTemplates`**: Modifies templates of an existing model.
110- **`model.updateModelStyling`**: Modifies CSS styling of an existing model.
111- **`model.modelFieldAdd`**: Adds a new field to an existing model.
112- **`model.modelFieldRemove`**: Removes a field from an existing model.
113 
114### Media Service (`media.*`)
115- **`media.retrieveMediaFile`**: Retrieves the base64-encoded contents of a media file.
116- **`media.getMediaFilesNames`**: Gets names of media files matching a glob pattern.
117- **`media.storeMediaFile`**: Stores a media file (from base64, path, or URL).
118- **`media.deleteMediaFile`**: Deletes a specified media file.
119 
120## Development
121 
122To set up for development:
123 
124```bash
125uv sync
126source .venv/bin/activate
127 
128uv pip install -e .
129```
130 
131### Running Tests
132 
133```bash
134pytest
135```
136 
137## Todo
138 
139- [ ] Finish adding all AnkiConnect tools
140