mkrech/anki-mcp-server

Anki MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact with Anki flashcard software through AnkiConnect.

Features

Tools

• list_decks - List all available Anki decks
• create_deck - Create a new Anki deck
• create_note - Create a new note (Basic or Cloze)
• batch_create_notes - Create multiple notes at once
• search_notes - Search for notes using Anki query syntax
• get_note_info - Get detailed information about a note
• update_note - Update an existing note
• delete_note - Delete a note
• list_note_types - List all available note types
• create_note_type - Create a new note type
• get_note_type_info - Get detailed structure of a note type

Resources

• anki://decks/all - Complete list of available decks
• anki://note-types/all - List of all available note types
• anki://note-types/all-with-schemas - Detailed structure information for all note types
• anki://note-types/{modelName} - Detailed structure information for a specific note type

Prerequisites

1. Anki installed and running
2. AnkiConnect add-on installed in Anki

Installation

Development Installation

# Clone the repository
git clone <repository-url>
cd anki-tutor

# Create virtual environment and install
uv venv
uv pip install -e ".[dev]"

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": ["run", "anki-mcp-server"]
    }
  }
}

Using Custom AnkiConnect Port

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": ["run", "anki-mcp-server", "--port", "8080"]
    }
  }
}

Usage Examples

Create a Basic Card

"Create an Anki card in the 'Default' deck:
Front: What is the capital of France?
Back: Paris"

Create a Cloze Card

"Create a cloze card in the 'Programming' deck:
In Python, {{c1::list comprehensions}} provide a concise way to create {{c2::lists}}."

Batch Create Cards

"Create 5 vocabulary cards for Spanish in the 'Spanish' deck from this list:
- hello: hola
- goodbye: adiós
- thank you: gracias
- please: por favor
- you're welcome: de nada"

Workflow: PDF to Anki Pipeline

This project supports a complete pipeline for converting educational PDFs into Anki flashcards:

Phase 1: PDF Processing

PDF → Docling Raw JSON → Intermediate JSON

Step 1: Convert PDF to Docling Raw

• Uses Docling DocumentConverter to extract document structure
• Preserves sections, tables, images, formulas, and hierarchy
• Output: *_docling.json and *_docling.md files
• Location: data/input/intermediate/docling_raw/

Step 2: Convert to Intermediate Format

• Transforms Docling output into structured sections
• Extracts hierarchy, metadata, and content relationships
• Output: *.json files with standardized structure
• Location: data/input/intermediate/

Phase 2: Flashcard Generation & Import

Intermediate JSON → LLM via MCP → Anki (via AnkiConnect)

Step 3: Generate Flashcards via LLM

The LLM analyzes intermediate JSON content and generates flashcards with a proven distribution:

• 55% Cloze cards - Fill-in-the-blank for definitions, formulas, concepts
• 30% KPRIM cards - Four statements with True/False evaluation
• 10% Multiple Choice - Multiple correct answers possible
• 5% Single Choice - One correct answer

Step 4: Batch Import to Anki

• Create deck structure via create_deck tool
• Import cards in batches of 10-12 via batch_create_notes
• Use allow_duplicate=true parameter when encountering similar cards
• Generate import report in data/progress/ directory

Complete Example

1. Source: data/input/pdfs/pgm/exams/midterm-exam.pdf
   
2. Convert to Docling Raw:
   → data/input/intermediate/docling_raw/midterm-exam_docling.json
   → data/input/intermediate/docling_raw/midterm-exam_docling.md
   
3. Convert to Intermediate:
   → data/input/intermediate/midterm-exam.json
   
4. Generate & Import:
   → LLM analyzes content
   → Generates 50 cards (28 Cloze, 15 KPRIM, 5 MC, 2 SC)
   → Creates deck: PGM::MidtermExam
   → Imports in 5 batches (10-12 cards each)
   
5. Report:
   → data/progress/midterm-exam-import-report.md

Best Practices

Batch Import Strategy:

• Process 10-12 cards per batch for optimal reliability
• Monitor success rates and adjust if needed
• Use allow_duplicate=true for KPRIM cards with similar patterns

Quality Tracking:

• Generate detailed import reports after each session
• Track card distribution, coverage, and success rates
• Store reports in data/progress/ for reference

Card Distribution:

• Maintain 55/30/10/5 split for comprehensive learning
• Balance theoretical knowledge (Cloze) with application (KPRIM/MC/SC)
• Cover all major topics from source material

Development

Running Tests

pytest

Code Quality

# Format code
ruff format .

# Lint code
ruff check .

# Auto-fix issues
ruff check --fix .

Running Locally

# Default port (8765)
uv run anki-mcp-server

# Custom port
uv run anki-mcp-server --port 8080

# With debug logging
uv run anki-mcp-server --log-level DEBUG

Architecture

• client.py - AnkiConnect API wrapper (anti-corruption layer)
• tools.py - MCP tool handlers for all Anki operations
• resources.py - MCP resource handlers with caching
• server.py - Main MCP server implementation
• __main__.py - CLI entry point

Troubleshooting

"Failed to connect to Anki"

1. Ensure Anki is running
2. Verify AnkiConnect add-on is installed
3. Check AnkiConnect is listening on the correct port (default: 8765)
4. Restart Anki and try again

"Deck not found"

• Create the deck manually in Anki first, or
• Use the create_deck tool before creating notes

"Note type not found"

• Use list_note_types to see available types
• Use get_note_type_info to see required fields
• Ensure field names match exactly (case-sensitive)

License

MIT License