dhkim0124/anki-mcp-server
If you are the rightful owner of anki-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
anki-mcp-server is a Model Context Protocol server that connects Claude and Anki, allowing users to create flashcards using natural language.
anki-mcp-server
Read this in other languages: ,
A Model Context Protocol (MCP) server that connects Claude and Anki, allowing you to create, manage, and enrich flashcard decks through natural language — without ever opening the Anki UI.
Requirements
- Python 3.9 or higher
- Anki 2.1.x or higher
- AnkiConnect add-on
- Claude Desktop (or any MCP-compatible client)
Installation
1. Set up Anki and AnkiConnect
- Install Anki.
- Install the AnkiConnect add-on:
- In Anki, go to
Tools > Add-ons > Get Add-ons - Enter code
2055492159and click OK - Restart Anki
- In Anki, go to
- Verify it works by visiting
http://localhost:8765— you should seeAnkiConnect v.6.
2. Install anki-mcp-server
git clone https://github.com/dhkim0124/anki-mcp-server.git
cd anki-mcp-server
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
3. Configure Claude Desktop
Edit your Claude Desktop config file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"anki-mcp": {
"command": "python",
"args": ["/absolute/path/to/anki_server.py"]
}
}
}
Usage
With Anki running in the background, you can ask Claude things like:
- "Create a Python deck with Code style and add 10 cards about decorators"
- "Show me my decks and their stats"
- "Search for cards tagged 'sql' and update the one about indexes"
- "Create a custom dark-mode deck with fields: Word, Definition, Example, Audio"
- "Upload this image and attach it to a new card in my Biology deck"
- "Sync my collection with AnkiWeb"
The server guides the conversation — it asks clarifying questions about deck, style, and card type before creating anything, and always asks for confirmation before destructive operations.
Available Tools
Deck Management
| Tool | Description |
|---|---|
list_decks | List all decks with stats (total, new, due, learning cards) |
create_deck | Create a new deck (supports nested decks with ::) |
delete_deck | Delete a deck — requires explicit confirmation |
Card Operations
| Tool | Description |
|---|---|
create_card | Create a single Basic card (front/back) |
create_card_batch | Create multiple cards in one call |
create_card_custom | Create a card using a custom note type, with optional audio/image attachments |
search_cards | Search using Anki's query syntax (tags, text, deck filters) |
update_card | Edit fields and tags of an existing card |
delete_cards | Delete one or more cards — requires explicit confirmation |
Note Types & Styling
| Tool | Description |
|---|---|
create_note_type | Create a custom note type with chosen fields, CSS style, and HTML templates |
get_note_types | List all available note types and their fields |
update_note_type_style | Update the CSS of an existing note type |
update_note_type_template | Update the HTML templates of an existing note type |
Media & Sync
| Tool | Description |
|---|---|
add_media | Upload an image or audio file (base64) to Anki's media folder |
sync_anki | Sync your local collection with AnkiWeb |
Style Templates
Four built-in styles are available via the style parameter in create_note_type:
| Style | Key | Best for |
|---|---|---|
| Default | "default" | General use |
| Duolingo | "duolingo" | Language learning, gamified feel |
| Dark Mode | "dark" | Night studying, reduced eye strain |
| Code | "code" | Programming, algorithms |
| Custom | "custom" | Full control — you provide the CSS |
For custom style, describe what you want in natural language and Claude generates the CSS:
"Dark blue background, mint green accents, smooth fade-in animation"
All custom CSS is validated to block javascript: URLs, <script> tags, and inline event handlers before being sent to Anki.
Project Structure
anki-mcp-server/
├── anki_server.py # MCP tool definitions and AnkiConnect client
├── config.py # Constants: URL, API version, media limits
├── instructions.py # LLM system instructions for conversational behavior
├── templates.py # Built-in CSS themes, CSS validation, HTML generators
└── tests/
├── test_anki_server.py # Tests for all tools (mocked AnkiConnect)
└── test_templates.py # Tests for template logic and CSS validation
Running Tests
pip install pytest pytest-asyncio
pytest tests/ -v
All tests mock AnkiConnect via httpx — no running Anki instance required.
Troubleshooting
- Anki must be open: The MCP server requires Anki to be running.
- AnkiConnect not responding: Visit
http://localhost:8765to confirm it's active. - Windows firewall: You may need to allow Anki through the firewall for AnkiConnect to work.
- Restart everything: If issues persist, restart Anki, Claude Desktop, and re-check the config file path.
Contributing
Fork the repository and open a pull request. Contributions are welcome in:
- New card types or template styles
- Additional language support
- Interface and UX improvements
- Documentation
License
MIT License — see for details.
