# anki-mcp

An MCP (Model Context Protocol) server that enables Claude Code to create and manage Anki flashcards. Create flashcards during your coding sessions and review them later on mobile via AnkiWeb sync.

## Why

Learning happens during work, but knowledge fades without review. This tool lets you capture learnings as flashcards without leaving your terminal, then review them on your phone using Anki's spaced repetition system.

## Features

- Create single or batch flashcards with tags
- Create and list decks (supports nested decks via `::` syntax)
- Search cards using Anki's query syntax
- Get deck statistics (new, due, total cards)
- Sync to AnkiWeb for mobile access
- Check AnkiConnect connection status

## Prerequisites

- macOS (tested on macOS 14+)
- Python 3.12+
- [uv](https://github.com/astral-sh/uv) package manager
- Claude Code CLI

## Setup

### 1. Install Anki Desktop

```bash
brew install --cask anki
```

### 2. Install AnkiConnect Add-on

1. Open Anki
2. Go to **Tools** > **Add-ons** > **Get Add-ons...**
3. Enter code: `2055492159`
4. Click **OK**
5. Restart Anki

### 3. Configure AnkiConnect Port (if needed)

AnkiConnect defaults to port 8765. If that port is in use, change it:

1. Go to **Tools** > **Add-ons**
2. Select **AnkiConnect** > **Config**
3. Change `"webBindPort": 8765` to another port (e.g., `8766`)
4. Restart Anki

The config file is located at:
```
~/Library/Application Support/Anki2/addons21/2055492159/config.json
```

### 4. Clone and Install anki-mcp

```bash
git clone https://github.com/hbd/anki-mcp.git
cd anki-mcp
uv sync
```

### 5. Configure Claude Code

Add to your `.mcp.json` (project-level) or `~/.claude/settings.json` (global):

```json
{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/anki-mcp",
        "fastmcp",
        "run",
        "server.py"
      ],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8766"
      }
    }
  }
}
```

Update the `--directory` path and `ANKI_CONNECT_URL` port to match your setup.

### 6. Restart Claude Code

The MCP server will be available after restart.

### 7. Configure AnkiWeb Sync (for mobile access)

1. Create an account at [ankiweb.net](https://ankiweb.net)
2. In Anki desktop: **Tools** > **Preferences** > **Syncing**
3. Sign in with your AnkiWeb credentials
4. Install AnkiMobile (iOS, paid) or AnkiDroid (Android, free)
5. Sign in to the mobile app with the same account

## Usage

Once configured, you can use natural language in Claude Code:

```
"Create a flashcard about Python decorators"
"Add these concepts to my Programming deck"
"Sync my cards to AnkiWeb"
"How many cards are due today?"
```

### Available Tools

| Tool | Description |
|------|-------------|
| `list_decks` | List all Anki decks |
| `create_deck` | Create a new deck |
| `add_flashcard` | Add a single flashcard |
| `add_flashcards` | Add multiple flashcards in batch |
| `search_cards` | Search using Anki query syntax |
| `get_deck_stats` | Get deck statistics |
| `sync_anki` | Trigger AnkiWeb sync |
| `anki_connection_status` | Check if AnkiConnect is responding |

### Search Query Examples

```
deck:Default           # Cards in Default deck
tag:python             # Cards with python tag
is:new                 # New cards not yet studied
is:due                 # Cards due for review
added:1                # Cards added today
front:*decorator*      # Cards with "decorator" in front
```

## Architecture

```
Claude Code --> MCP Server --> AnkiConnect --> Anki Desktop
                                                    |
                                               AnkiWeb (cloud)
                                                    |
                                            Mobile App (iOS/Android)
```

## Requirements

- Anki desktop must be running for the MCP server to work
- AnkiConnect add-on must be installed and enabled
- Sync is not automatic - use the `sync_anki` tool or sync manually in Anki

## Troubleshooting

### "AnkiConnect not responding"

- Ensure Anki desktop is running
- Check that AnkiConnect is installed (Tools > Add-ons)
- Verify the port in your config matches AnkiConnect's port

### Port conflict

If port 8765 is in use:
1. Check what's using it: `lsof -i :8765`
2. Change AnkiConnect to a different port (see step 3 above)
3. Update `ANKI_CONNECT_URL` in your MCP config

### Sync fails with "auth not configured"

Sign in to AnkiWeb in Anki desktop (Tools > Preferences > Syncing).

## License

MIT