# 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/