# anki-mcp

A thin **Model Context Protocol (MCP)** adapter that lets AI assistants (Claude Code, Hermes Agent, etc.) create and manage Anki cards directly — via [AnkiConnect](https://foosoft.net/projects/anki-connect/).

No custom AI app. The AI stays the intelligence layer; this server is just a bridge to Anki.

```
Claude Code / Hermes / ChatGPT
          │  MCP (stdio)
          ▼
    anki-mcp server
          │  AnkiConnect HTTP (localhost:8765)
          ▼
    Anki Desktop + AnkiConnect add-on
          │  sync
          ▼
       AnkiWeb ──► Anki mobile (iOS/Android)
```

---

## Features

| Tool | Description |
|------|-------------|
| `list_decks` | List all decks with card counts |
| `create_deck` | Create a deck if it doesn't exist |
| `create_card` | Basic front/back card |
| `create_cloze` | Cloze deletion card (`{{c1::...}}`) |
| `create_cards` | Batch-create many cards at once |
| `search_cards` | Full-text search (Anki query syntax) |
| `update_card` | Update a card's front/back by note ID |
| `delete_card` | Delete a card by note ID |

---

## Setup

### 1. Install Anki Desktop

Download and install from <https://apps.ankiweb.net/>. Start it once and sync with your AnkiWeb account so mobile sync works.

### 2. Install the AnkiConnect add-on

AnkiConnect exposes Anki over a local HTTP API on `localhost:8765`.

**Option A — Anki add-on browser (easiest):**

1. In Anki: **Tools → Add-ons → Get Add-ons…**
2. Enter the code **`2055492159`** and install.

**Option B — manual (Git):**

```bash
cd "$APPDATA/Anki2/addons21"           # Windows
# or: ~/.local/share/Anki2/addons21   (Linux)
# or: ~/Library/Application Support/Anki2/addons21  (macOS)

git clone --depth 1 https://github.com/FooSoft/anki-connect.git 2055492159
cd 2055492159
cp plugin/*.py plugin/*.json plugin/*.md .
rm -rf plugin tests .git 2>/dev/null
```

3. Restart Anki. Verify it's up:

```bash
curl -s http://127.0.0.1:8765 -X POST -d '{"action":"version","version":6}'
# → {"result": 6, "error": null}
```

### 3. Run the MCP server

```bash
pip install mcp
python server.py
```

The server speaks MCP over stdio. Anki Desktop must be running (with AnkiConnect loaded) for tools to work.

---

## Configure in a client

### Hermes Agent

Add to `~/.hermes/config.yaml` (or `%USERPROFILE%\AppData\Local\hermes\config.yaml` on Windows):

```yaml
mcp_servers:
  anki:
    command: python
    args:
      - /absolute/path/to/server.py
    timeout: 60
    connect_timeout: 30
```

Then reload MCP in-session (`/reload-mcp`) or restart. Tools appear as `mcp_anki_*`.

### Claude Code

```bash
claude mcp add anki -- python /absolute/path/to/server.py
```

---

## Usage

Once wired up, just tell the AI what you want:

> *"Add a card to my System Design deck: front = 'Why does consistent hashing use virtual nodes?', back = 'To distribute keys more uniformly.'"*

> *"Make Anki cards from the important concepts we just discussed."*

### Card-generation rules (put these in your AI instructions)

- One concept per card.
- Prefer questions that require recall.
- Avoid huge answers.
- Don't create cards for trivial facts.
- Use cloze cards where appropriate.
- Add source/topic tags.

---

## Sync to mobile

MCP-created cards live in Anki Desktop until you sync. Trigger a sync:

- Manually: Anki → **Sync** (or press `Y`), or
- Via AnkiConnect: `curl -s http://127.0.0.1:8765 -X POST -d '{"action":"sync","version":6}'`

Then sync the Anki mobile app to pull the new cards.

---

## Requirements

- Python 3.10+
- `mcp` package (`pip install mcp`)
- Anki Desktop (running)
- AnkiConnect add-on

---

## License

MIT