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 package manager
• Claude Code CLI

Setup

1. Install Anki Desktop

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

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):

{
  "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
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