anki-mcp-server

Read this in other languages: English, 한국어

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

1. Install Anki.
2. Install the AnkiConnect add-on:
   • In Anki, go to Tools > Add-ons > Get Add-ons
   • Enter code 2055492159 and click OK
   • Restart Anki
3. Verify it works by visiting http://localhost:8765 — you should see AnkiConnect 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:8765 to 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 LICENSE for details.