MCP 服务器

AnkiMCP Server

Exposes Anki flashcard collections to AI assistants via MCP, enabling AI-powered study sessions, card creation, deck management, and review workflows. Supports comprehensive collection operations including search, media management, and note type customization.

README

AnkiMCP Server (Addon)

An Anki addon that exposes your collection to AI assistants via the Model Context Protocol (MCP).

What is this?

AnkiMCP Server runs a local MCP server inside Anki, allowing AI assistants like Claude to interact with your flashcard collection. This enables AI-powered study sessions, card creation, and collection management.

Part of the ankimcp.ai project.

Note on First Run

On first run, this addon downloads pydantic_core (~2MB) from PyPI. This is required because pydantic_core contains platform-specific binaries (Windows/macOS/Linux) that cannot be bundled in a single addon file.

Features

Local HTTP server - Runs on http://127.0.0.1:3141/ by default
MCP protocol - Compatible with any MCP client (Claude Desktop, etc.)
Auto-start - Server starts automatically when Anki opens
Tunnel-friendly - Works with Cloudflare Tunnel, ngrok, etc.
Cross-platform - Works on macOS, Windows, and Linux (x64 and ARM)

Installation

From AnkiWeb (recommended)

Open Anki and go to Tools → Add-ons → Get Add-ons...
Enter code: 124672614
Restart Anki

From GitHub Releases

Download anki_mcp_server.ankiaddon from Releases
Double-click to install, or use Tools → Add-ons → Install from file...
Restart Anki

Usage

The server starts automatically when you open Anki. Check status via Tools → AnkiMCP Server Settings...

Connect with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "anki": {
      "url": "http://127.0.0.1:3141/"
    }
  }
}

Configuration

Edit via Anki's Tools → Add-ons → AnkiMCP Server → Config:

{
  "mode": "http",
  "http_port": 3141,
  "http_host": "127.0.0.1",
  "cors_origins": [],
  "cors_expose_headers": ["mcp-session-id", "mcp-protocol-version"],
  "auto_connect_on_startup": true
}

CORS Configuration

To allow browser-based MCP clients (like web-hosted MCP Inspector), add allowed origins:

{
  "cors_origins": ["https://inspector.example.com", "http://localhost:5173"]
}

Use ["*"] to allow all origins (not recommended for production).

The cors_expose_headers setting controls which response headers browsers can read. The defaults (mcp-session-id, mcp-protocol-version) are required for the MCP Streamable HTTP protocol to work in browsers.

Available Tools

Essential Tools

Tool	Description
`sync`	Synchronize collection with AnkiWeb
`list_decks`	List all decks in the collection
`create_deck`	Create a new deck
`find_notes`	Search for notes using Anki's search syntax
`notes_info`	Get detailed information about notes
`add_note`	Add a new note to a deck
`update_note_fields`	Update fields of existing notes
`delete_notes`	Delete notes from the collection
`get_due_cards`	Get cards due for review
`present_card`	Get card content for review
`rate_card`	Rate a card after review (Again/Hard/Good/Easy)
`model_names`	List available note types
`model_field_names`	Get field names for a note type
`model_styling`	Get CSS styling for a note type
`update_model_styling`	Update CSS styling for a note type
`create_model`	Create a new note type
`store_media_file`	Store a media file (image/audio)
`get_media_files_names`	List media files matching a pattern
`delete_media_file`	Delete a media file

GUI Tools

These tools interact with Anki's user interface:

Tool	Description
`gui_browse`	Open the card browser with a search query
`gui_add_cards`	Open the Add Cards dialog
`gui_edit_note`	Open the note editor for a specific note
`gui_current_card`	Get info about the currently displayed card
`gui_show_question`	Show the question side of current card
`gui_show_answer`	Show the answer side of current card
`gui_select_card`	Select a specific card in the reviewer
`gui_deck_browser`	Navigate to deck browser
`gui_undo`	Undo the last operation

Resources

Resource	Description
`system_info`	Anki version and system information

Prompts

Prompt	Description
`review_session`	Guided review session workflow

Requirements

Anki 25.x or later (Python 3.13)

Architecture

The addon runs an MCP server in a background thread with HTTP transport (FastMCP + uvicorn). All Anki operations are bridged to the main Qt thread via a queue system, following the same proven pattern as AnkiConnect.

For details, see Anki Add-on Development Documentation.

Development

Running E2E Tests

E2E tests run against a real Anki instance in Docker using headless-anki.

# Install test dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

# Build the addon
./package.sh

# Start Anki container
cd .docker && docker compose up -d && cd ..

# Run tests (waits for server automatically)
pytest tests/e2e/ -v

# Stop container
cd .docker && docker compose down

Or use the Makefile shortcuts:

make e2e        # Build, start container, run tests, stop
make e2e-up     # Just start container
make e2e-test   # Just run tests
make e2e-down   # Just stop container