Content
# anki-mcp-server
[](https://smithery.ai/server/@dhkim0124/anki-mcp-server)
*Read this in other languages: [English](README.md), [한국어](docs/README_KO.md)*
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](https://ankiweb.net/shared/info/2055492159) add-on
- Claude Desktop (or any MCP-compatible client)
## Installation
### 1. Set up Anki and AnkiConnect
1. Install [Anki](https://apps.ankiweb.net/).
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
```bash
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`
```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
```bash
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](LICENSE) for details.
