Anki Model Context Protocol (MCP) Server

A high-performance Model Context Protocol (MCP) server enabling AI assistants (Claude Desktop, Claude Code, Antigravity, Codex, Cursor, etc.) to directly manage Anki flashcards, decks, notetypes, tags, media, and searches.

⚡ Universal File-Based I/O Architecture

Modern flashcards (especially with HTML markup, syntax-highlighted code blocks, and LaTeX math formulas) are large payloads. Streaming these through JSON-RPC tool parameters or returning full card content directly to the model causes token exhaustion, truncated outputs, and context window saturation.

This server implements Universal File-Based Input and Output (File-Based I/O):

1. Zero In-Band Token Bloat: Flashcard mutations, queries, searches, and schema introspections accept input JSON file paths and write full structured output to disk.

2. Compact Telemetry Responses: Every tool call returns bounded metadata summaries ($< 150$ tokens) with status, IDs, affected counts, and the resolved output_file path.

3. Atomic Batch Ingestion: Hundreds of cards can be written to a single JSON payload and ingested in an atomic SQLite transaction in milliseconds.

4. Cross-Platform Temp Storage: Outputs default to the OS temporary directory (%TEMP%\anki_mcp on Windows, /tmp/anki_mcp on Linux/macOS) and can be overridden via ANKI_MCP_OUTPUT_DIR.

Related MCP server: Anki MCP Server

Features

• ⚡ Fast Direct Bridge: Interacts directly with Anki's collection database (collection.anki2) via the official anki Python engine with zero HTTP overhead.

• 🔒 Non-Blocking Connection Lifecycle: Uses per-request open/close context management (~2.7ms) so database locks are immediately released and Anki Desktop is not locked out.

• 🪟 Cross-Platform: Native support for Windows, macOS, and Linux, with automatic collection discovery in standard OS locations.

• 🗂️ Hierarchical Decks: Full support for nested deck creation (e.g. Computer Science::Algorithms::Trees).

• 📝 Rich Card Formats: Supports Standard/Basic cards, Cloze deletions ({{c1::...}}), custom fields, and LaTeX math formulas ($...$ and $$...$$).

• 🔍 Query Engine: Full support for Anki's search syntax (deck:Languages tag:grammar, is:due, added:7, "Recursion").

• 🏷️ Tag Management: Hierarchical tagging and bulk tag additions/removals.

• 📦 Batch Creation: High-throughput batch card addition in single atomic operations via JSON payloads.

• 💾 Deck Export: Native packaging to .apkg, .colpkg, and .json.

• 💡 MCP Prompts & Resources: Built-in resources (anki://decks, anki://stats) and structured card generation prompt (flashcard_generator).

Installation & Setup

This project uses uv for fast, reproducible Python environment management.

Clone and Install

git clone https://github.com/debnath-d/anki-mcp-server.git
cd anki-mcp-server
uv sync

Run Server

uv run anki-mcp-server

Client Configurations

1. Claude Desktop

Add the server to your Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Windows Configuration

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\anki-mcp-server",
        "run",
        "anki-mcp-server"
      ]
    }
  }
}

macOS / Linux Configuration

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

2. Google Antigravity

Add to your Antigravity MCP configuration (~/.gemini/config/mcp_config.json):

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

3. Claude Code / Codex / CLI Clients

Start Claude Code with the MCP server:

claude --mcp-server "uv --directory '/path/to/anki-mcp-server' run anki-mcp-server"

🧠 Bundled Anki Agent Skill

This repository includes a production-ready Agent Skill (skills/anki) designed for AI coding assistants and agents (such as Google Antigravity, Claude Code, and other agents supporting the Agent Skills standard).

While the MCP server provides the mechanism (tools, file-based I/O, database access), the agent skill provides the policy and methodology (spaced-repetition knowledge formulation, card authoring heuristics, and multi-step runbooks).

What the Skill Provides

• Evolutionary Card Lifecycle: Rejects rigid academic dogma that forces complete pre-comprehension. Cards can start directly in Anki as rich problem statements (e.g. 150 NeetCode problems) or reading excerpts, evolving into atomic cards as you study.

• Token-Efficient Ingestion: Guides agents to assemble bulk payloads via scripts directly in the OS temporary directory (tempfile.gettempdir() / 'anki_mcp') without burning LLM context tokens analyzing each card upfront.

• Pragmatic Knowledge Formulation: Operationalized rules distilled from SuperMemo:

  • Atomicity (Minimum Information Principle) as an evolutionary target during review/refactoring.

  • Pragmatic allowances for small sets (2–4 items) and short sequences.

  • Contrastive pairing for confusable concepts to combat memory interference.

  • Context prefixes (e.g. [Python], [NeetCode]) and hierarchical tags.

  • Strict formatting for LaTeX ($...$, $$...$$) and code blocks (<pre><code>...</code></pre>).

• Execution Playbooks: Step-by-step runbooks for bulk script ingestion, interactive generation, leech triage (prop:lapses>=4), and deck restructuring.

• Query Cheatsheet: Quick reference for Anki search syntax (is:due, prop:lapses, tag:, deck:).

Installing the Skill

The skill adheres to the open Agent Skills standard and can be linked globally or per-project across your preferred agent environments:

1. Claude Code

• Global Install:

  • Linux / macOS:

    mkdir -p ~/.claude/skills
    ln -s "$(pwd)/skills/anki" ~/.claude/skills/anki

  • Windows (PowerShell):

    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills"
    New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\skills\anki" -Target "$PWD\skills\anki"

• Project-Specific Install: Link or copy directly into your repository's .claude/skills/:

  mkdir -p .claude/skills
  ln -s "$(pwd)/skills/anki" .claude/skills/anki

2. Google Antigravity

• Global Install:

  • Linux / macOS:

    mkdir -p ~/.gemini/config/skills
    ln -s "$(pwd)/skills/anki" ~/.gemini/config/skills/anki

  • Windows (PowerShell):

    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini\config\skills"
    New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.gemini\config\skills\anki" -Target "$PWD\skills\anki"

• Project-Specific Install: Link into .agents/skills/:

  mkdir -p .agents/skills
  ln -s "$(pwd)/skills/anki" .agents/skills/anki

3. Universal .agents/skills (Cursor, Codex, OpenHands)

• Global Install:

  • Linux / macOS:

    mkdir -p ~/.agents/skills
    ln -s "$(pwd)/skills/anki" ~/.agents/skills/anki

  • Windows (PowerShell):

    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
    New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.agents\skills\anki" -Target "$PWD\skills\anki"

• Project-Specific Install:

  mkdir -p .agents/skills
  ln -s "$(pwd)/skills/anki" .agents/skills/anki

Available MCP Tools

1. Deck Management

2. Notetypes (Models)

3. Flashcard & Note Ingestion & Mutation (File-Based)

4. Media, State Control & Export

5. Search & Discovery

6. Tag Management & Stats

Testing

Run the automated test suite and linter:

ruff check .
uv run python -m unittest discover -s tests

Important Notes & Troubleshooting

1. SQLite Database Lock: Anki uses exclusive file locks. The Anki desktop GUI application must be closed while the MCP server executes write operations to prevent anki.errors.DBError locks.

2. Collection Path Auto-Discovery:

   • Windows: Automatically detected in %APPDATA%\Anki2\<Profile>\collection.anki2 or %LOCALAPPDATA%\Anki2\<Profile>\collection.anki2.

   • macOS: Automatically detected in ~/Library/Application Support/Anki2/<Profile>/collection.anki2.

   • Linux: Automatically detected in ~/.local/share/Anki2/<Profile>/collection.anki2.

   • To use a custom location, set the ANKI_COLLECTION_PATH environment variable.

3. Output Cache: Tool outputs are stored in your OS temporary directory (%TEMP%\anki_mcp or /tmp/anki_mcp) by default. Set ANKI_MCP_OUTPUT_DIR to use a custom directory.