Anki MCP Server Addon
An Anki addon that implements an MCP server, enabling AI assistants to interact with Anki, the spaced repetition flashcard application.
Installation
npx anki-mcp-server-addonAsk AI about Anki MCP Server Addon
Powered by Claude Β· Grounded in docs
I know everything about Anki MCP Server Addon. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AnkiMCP Server (Addon)
Seamlessly integrate Anki with AI assistants through the Model Context Protocol
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.ankiaddonfrom Releases - Double-click to install, or use Tools β Add-ons β Install from file...
- Restart Anki
NixOS
With flakes (recommended)
Add the flake input and use the pre-built package:
# flake.nix
{
inputs.anki-mcp.url = "github:ankimcp/anki-mcp-server-addon";
outputs = { nixpkgs, anki-mcp, ... }: {
# Option A: Standalone β Anki with the addon pre-installed
environment.systemPackages = [
anki-mcp.packages.${system}.default
];
# Option B: Composable with other addons via overlay
nixpkgs.overlays = [ anki-mcp.overlays.default ];
environment.systemPackages = [
(pkgs.anki.withAddons [ pkgs.ankiAddons.anki-mcp-server ])
];
};
}
Without flakes
# configuration.nix
{ pkgs, ... }:
let
python3 = pkgs.python3;
ankiMcpPythonDeps = python3.withPackages (ps: with ps; [
mcp pydantic pydantic-settings starlette uvicorn anyio httpx websockets
]);
anki-mcp-server = pkgs.anki-utils.buildAnkiAddon (finalAttrs: {
pname = "anki-mcp-server";
version = "0.13.0";
src = pkgs.fetchFromGitHub {
owner = "ankimcp";
repo = "anki-mcp-server-addon";
rev = "v${finalAttrs.version}";
hash = ""; # nix will tell you the correct hash on first build
};
sourceRoot = "${finalAttrs.src.name}/anki_mcp_server";
});
ankiWithMcp = pkgs.anki.withAddons [ anki-mcp-server ];
ankiWrapped = pkgs.symlinkJoin {
name = "anki-with-mcp";
paths = [ ankiWithMcp ];
nativeBuildInputs = [ pkgs.makeWrapper ];
postBuild = ''
wrapProgram $out/bin/anki \
--prefix PYTHONPATH ':' "${ankiMcpPythonDeps}/${python3.sitePackages}"
'';
};
in
{
environment.systemPackages = [ ankiWrapped ];
}
Usage
The server starts automatically when you open Anki. Check status via Tools β AnkiMCP Server Settings...
Connect with Claude Desktop
Requires Node.js installed. Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"anki": {
"command": "npx",
"args": ["mcp-remote", "http://127.0.0.1:3141"]
}
}
}
Note: Claude Desktop doesn't natively support HTTP servers in its JSON config β
mcp-remotebridges the connection via stdio.
Connect with Claude Code
claude mcp add anki --transport http 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",
"http_path": "",
"cors_origins": [],
"cors_expose_headers": ["mcp-session-id", "mcp-protocol-version"],
"auto_connect_on_startup": true,
"disabled_tools": [],
"media_import_dir": "",
"media_allowed_types": [],
"media_allowed_hosts": []
}
Disabling Tools
Hide specific tools or actions from AI clients to reduce token usage:
{
"disabled_tools": [
"sync",
"card_management:bury",
"card_management:unbury"
]
}
"tool_name"β disables the entire tool"tool_name:action"β disables a specific action within a multi-action tool
Disabled tools are removed from the MCP schema entirely β AI clients never see them. Typos in tool/action names will produce console warnings.
Custom Path
Set http_path to serve the MCP endpoint under a custom path. Useful when exposing Anki via a tunnel (Cloudflare, ngrok) to avoid a fully open endpoint:
{
"http_path": "my-secret-path"
}
The server will be accessible at http://localhost:3141/my-secret-path/ instead of the root. Leave empty for default behavior.
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.
Media Security
Thanks to Hideaki Takahashi (Columbia University) for responsibly disclosing the media path traversal vulnerability.
The store_media_file tool validates all inputs to prevent path traversal and SSRF attacks:
- File paths are restricted to media files only (images, audio, video) via MIME type checking
- URLs must use
http://orhttps://and cannot target private/internal networks - Filenames are sanitized to remove path traversal sequences
Optional hardening via config:
{
"media_import_dir": "/Users/me/anki-media",
"media_allowed_types": ["application/pdf"],
"media_allowed_hosts": ["192.168.1.50", "my-nas.local"]
}
media_import_dirβ restrict file path imports to this directory tree (empty = no restriction)media_allowed_typesβ allow additional MIME types beyond image/audio/videomedia_allowed_hostsβ allow specific hosts to bypass private network blocking
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 |
add_notes | Batch-add up to 100 notes sharing the same deck and model. Uses Anki's native batch API for atomic undo. Supports partial success β individual failures don't affect others |
card_management | Manage cards with 9 actions: reposition (set learning order), change_deck (move between decks), bury/unbury (hide until tomorrow), suspend/unsuspend (indefinitely exclude from review), set_flag (color flags 0-7), set_due_date (reschedule with days DSL), forget_cards (reset to new) |
tag_management | Manage tags with 5 actions: add_tags/remove_tags (bulk add/remove on notes), replace_tags (swap one tag for another), get_tags (list all), clear_unused_tags (remove orphans) |
filtered_deck | Filtered deck lifecycle: create_or_update (create or modify filtered decks with search terms), rebuild (repopulate), empty (return cards to home decks), delete |
update_note_fields | Update fields of existing notes |
delete_notes | Delete notes from the collection |
get_due_cards | Get next due card for review (supports skip_images/skip_audio for voice mode) |
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 and descriptions 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) via base64, file path, or URL. File paths are validated against a media-type allowlist; URLs are checked for SSRF |
get_media_files_names | List media files matching a pattern |
delete_media_file | Move a media file to Anki's trash (recoverable via Check Media) |
FSRS Tools
| Tool | Description |
|---|---|
get_fsrs_params | Get FSRS scheduler parameters for deck presets |
set_fsrs_params | Update FSRS parameters (weights, desired retention, max interval) |
get_card_memory_state | Get FSRS memory state (stability, difficulty, retrievability) for cards |
optimize_fsrs_params | Run FSRS parameter optimization using Anki's built-in optimizer |
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 | URI | Description |
|---|---|---|
system_info | anki://system-info | Anki version, profile, and scheduler info |
query_syntax | anki://query-syntax | Anki search query syntax reference |
schema | anki://schema | Data model documentation (entities, fields, relationships) |
stats_today | anki://stats/today | Today's study statistics |
stats_forecast | anki://stats/forecast | 30-day review forecast |
stats_collection | anki://stats/collection | Overall collection statistics |
fsrs_config | anki://fsrs/config | FSRS configuration summary and parameters |
Prompts
| Prompt | Description |
|---|---|
review_session | Guided review session workflow (interactive, quick, or voice mode) |
Requirements
- Anki 25.07 or later (ships Python 3.13)
- Anki 25.02 and earlier ship Python 3.9, which is not supported β the MCP SDK requires Python 3.10+ (#8)
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
CI
E2E tests run automatically on push to any branch and on PRs to main. See .github/workflows/e2e.yml.
License
AGPL-3.0-or-later
Links
- ankimcp.ai - Project homepage
- MCP Protocol - Model Context Protocol specification
- Anki Add-on Docs - Official Anki addon development documentation
