# Anki MCP Server
MCP server providing programmatic access to Anki flashcard operations via AnkiConnect API.
## Features
- **list_decks** - List all Anki decks
- **list_cards** - List all flashcards in a specific deck
- **create_deck** - Create a new Anki deck
- **create_card** - Create a new flashcard in a deck
## Prerequisites
Before using this MCP server, you must have:
1. **Anki** desktop application installed and running
2. **AnkiConnect** plugin installed in Anki
- Plugin ID: 2055492159
- Install from: https://ankiweb.net/shared/info/2055492159
- Or install via Anki: Tools → Add-ons → Get Add-ons → Enter code `2055492159`
### Verifying AnkiConnect Installation
After installing AnkiConnect, verify it's working:
```bash
curl http://localhost:8765 -X POST -d '{"action": "version", "version": 6}'
```
You should see a response like: `{"result": 6, "error": null}`
If you get a connection error, make sure Anki is running.
## Installation
### Using uv (recommended)
```bash
# Clone or navigate to the project directory
cd mcp-server-anki
# Install dependencies
uv pip install -e .
```
### Using pip
```bash
cd mcp-server-anki
pip install -e .
```
## Configuration
Add the server to your MCP client configuration (e.g., `claude_desktop_config.json`):
```json
{
"mcpServers": {
"anki": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mcp-server-anki",
"run",
"mcp-server-anki"
]
}
}
}
```
Replace `/absolute/path/to/mcp-server-anki` with the actual path to the project directory.
### Alternative Configuration (without uv)
```json
{
"mcpServers": {
"anki": {
"command": "python",
"args": [
"-m",
"mcp_server_anki.server"
]
}
}
}
```
## Usage
### List Decks
```
List all my Anki decks
```
Response:
```json
{
"decks": ["Default", "Python", "System Design"]
}
```
### Create Deck
```
Create a new Anki deck called "Machine Learning"
```
Response:
```json
{
"deck_id": 1234567890123,
"message": "Deck 'Machine Learning' created successfully"
}
```
### Create Card
```
Add a flashcard to the "Python" deck with front "What is a decorator?" and back "A function that modifies another function"
```
Response:
```json
{
"note_id": 1234567890,
"message": "Card created successfully in deck 'Python'"
}
```
### List Cards
```
Show me all cards in the "Python" deck
```
Response:
```json
{
"cards": [
{
"note_id": 1234567890,
"fields": {
"Front": "What is a decorator?",
"Back": "A function that modifies another function"
},
"tags": ["python", "advanced"]
}
]
}
```
## Example Workflow
```
Create a new Anki deck called 'System Design' and add a card with front 'What is CAP theorem?' and back 'Consistency, Availability, Partition Tolerance trade-off'
```
This will:
1. Create the deck "System Design"
2. Add the flashcard to the deck
3. Confirm both operations succeeded
## Error Handling
### Anki Not Running
If Anki is not running or AnkiConnect is not installed:
```
Error: Could not connect to Anki. Is Anki running with AnkiConnect installed?
```
**Solution**: Start Anki and ensure AnkiConnect is installed.
### Deck Not Found
If you try to list cards from a non-existent deck:
```
Error: Deck 'NonExistent' not found
```
**Solution**: Create the deck first or check the deck name spelling.
### Card Creation Failed
If you try to create a card in a non-existent deck:
```
Error: AnkiConnect error: cannot create note because it is a duplicate
```
**Solution**: Ensure the deck exists or check for duplicate cards.
## Limitations
- Only supports "Basic" note type (two-sided cards)
- No support for custom note types
- No card editing or deletion
- No deck editing or deletion
- No media attachments (images/audio)
- Only works with local Anki instance on localhost:8765
## Development
### Project Structure
```
mcp-server-anki/
├── mcp_server_anki/
│ ├── __init__.py
│ ├── server.py # MCP server and tool definitions
│ └── anki_client.py # AnkiConnect HTTP client
├── pyproject.toml
└── README.md
```
### Running Tests Manually
1. Start Anki with AnkiConnect installed
2. Use the MCP client to test each operation:
- List existing decks
- Create a new deck
- Create a card in the deck
- List cards in the deck
- Test error conditions (Anki not running, deck not found)
## Troubleshooting
### "Could not connect to Anki"
- Verify Anki is running
- Verify AnkiConnect is installed (Tools → Add-ons)
- Test AnkiConnect with curl (see verification section above)
### "Deck not found"
- Deck names are case-sensitive
- Check spelling and capitalization
- List all decks to see available names
### "Cannot create note because it is a duplicate"
- Anki prevents duplicate cards by default
- Either use different content or allow duplicates in Anki settings
## License
MIT
## Links
- AnkiConnect: https://github.com/FooSoft/anki-connect
- Anki: https://apps.ankiweb.net/
- MCP: https://modelcontextprotocol.io/
