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:

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)

# Clone or navigate to the project directory
cd mcp-server-anki

# Install dependencies
uv pip install -e .

Using pip

cd mcp-server-anki
pip install -e .

Configuration

Add the server to your MCP client configuration (e.g., claude_desktop_config.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)

{
  "mcpServers": {
    "anki": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_anki.server"
      ]
    }
  }
}

Usage

List Decks

List all my Anki decks

Response:

{
  "decks": ["Default", "Python", "System Design"]
}

Create Deck

Create a new Anki deck called "Machine Learning"

Response:

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

{
  "note_id": 1234567890,
  "message": "Card created successfully in deck 'Python'"
}

List Cards

Show me all cards in the "Python" deck

Response:

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