AnkiMCP Server

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.

A second native dependency, rpds (from rpds-py), is handled the same way — but it is almost never downloaded: Anki already ships rpds as a transitive dependency of its own jsonschema, so the addon just imports it. The download only kicks in on the rare install where that import fails. Both downloads are cached under Anki's own data folder (outside the addon's own folder, so it survives addon updates cleanly on every OS), falling back to the addon's _cache/ directory when that location isn't available — so either way they happen once, not on every launch. The old in-folder fallback cache is only ever removed once the outside-the-folder cache has proven itself usable (a successful load from it) and is never touched while a native module is still loaded from it — a failed first attempt (e.g. offline) leaves the old cache untouched rather than destroyed.

Features

• Local HTTP server - Runs on http://127.0.0.1:3141/ by default
• Remote tunnel - Access your collection from anywhere via a public HTTPS URL
• MCP protocol - Compatible with any MCP client (Claude Desktop, etc.)
• Auto-start - HTTP server starts automatically when Anki opens
• Tunnel-friendly - Works with Cloudflare Tunnel, ngrok, or the built-in tunnel (exposing the HTTP server this way also requires extending the allowed hosts/origins)
• DNS-rebinding protection - The HTTP server validates Host/Origin headers against a loopback allowlist by default; extend it for tunnel/reverse-proxy exposure
• Optional API key - Require an Authorization: Bearer token on the HTTP transport via http_api_key (AnkiConnect-style; empty = disabled)
• Toolbar indicator - A ● AnkiMCP item in the top toolbar shows tunnel connection state at a glance (opt out via show_toolbar_indicator)
• Diagnostic logging - Opt-in log_to_file writes a rotating, secret-redacted log to user_files/ankimcp.log, with Open log folder / Copy diagnostics buttons in settings
• Field management - Add, rename, and reposition note-type fields via the model_field_* tools (with an opt-in destructive model_field_remove)
• Bulk card stats - The read-only cards_stats tool returns compact per-card scheduling metrics (type/queue/interval/tags/dueToday) for a whole deck including subdecks, FSRS-independent — a lean bulk read for analytics
• GUI review sessions - Hands-free review in Anki's own reviewer window: gui_deck_review opens a deck, gui_answer_card presses the answer button for you. Opt-in, hidden until named in enabled_opt_in_tools
• MCP tool annotations - Every tool declares a title, readOnlyHint, destructiveHint and openWorldHint (plus idempotentHint on write tools that are safe to repeat), so clients can show readable names and confirm before data-changing calls
• Cross-platform - Works on macOS, Windows, and Linux (x64 and ARM)

Installation

From AnkiWeb (recommended)

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

From GitHub Releases

1. Download anki_mcp_server.ankiaddon from Releases
2. Double-click to install, or use *Tools → Add-ons → Install from file...*
3. 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.20.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-remote bridges the connection via stdio.

Connect with Claude Code

claude mcp add anki --transport http http://127.0.0.1:3141/

Opencode

opencode mcp add anki --url http://127.0.0.1:3141/

Tunnel (Remote Access)

The built-in tunnel gives your Anki collection a public HTTPS URL, so AI assistants can reach it from anywhere — no port forwarding or reverse proxy needed. The collection is relayed through a WebSocket tunnel server (wss://tunnel.ankimcp.ai by default). Requires an ankimcp.ai account to log in.

How to connect:

1. Open *Tools -> AnkiMCP Server Settings...*
2. Click Connect Tunnel
3. If not logged in, a login dialog appears — it shows a one-time code; click Open Browser and enter that code at the verification URL (OAuth 2.0 device flow)
4. Once connected, a public tunnel URL is displayed (e.g., https://tunnel.ankimcp.ai/e3439277-9d1e-47a1-b961-d193a4590da0)
5. Use this URL in your AI client instead of http://127.0.0.1:3141

Using with Claude Desktop:

Replace the localhost URL with your tunnel URL in the Claude Desktop config:

{

"mcpServers": { "anki": { "command": "npx", "args": ["mcp-remote", "https://tunnel.ankimcp.ai/ "] } } }

Using with Claude Code:

claude mcp add anki --transport http https://tunnel.ankimcp.ai/<your-tunnel-id>

Disconnect vs. Logout:

• Disconnect closes the tunnel connection. Credentials stay on disk — next Connect reconnects without re-login.
• Logout deletes credentials. Next Connect triggers the login dialog again.

Tunnel config fields (for advanced users / self-hosters):

• tunnel_server_url — WebSocket URL of the tunnel relay server (default: wss://tunnel.ankimcp.ai)
• tunnel_client_id — OAuth client identifier (default: ankimcp-cli)

Credentials are stored in the addon's own user_files/credentials.json (preserved across addon updates). They are not shared with the AnkiMCP CLI — the CLI keeps its own credentials under ~/.ankimcp/, so you log in to the addon and the CLI independently. The on-disk format is identical between the two.

Configuration

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

{

"http_enabled": true, "http_port": 3141, "http_host": "127.0.0.1", "http_path": "", "http_allowed_hosts": [], "http_allowed_origins": [], "http_api_key": "", "cors_origins": [], "cors_expose_headers": ["mcp-protocol-version"], "disabled_tools": [], "enabled_destructive_tools": [], "enabled_opt_in_tools": [], "max_notes_per_batch": 100, "tunnel_server_url": "wss://tunnel.ankimcp.ai", "tunnel_client_id": "ankimcp-cli", "media_import_dir": "", "media_allowed_types": [], "media_allowed_hosts": [], "show_settings_menu_item": true, "show_toolbar_indicator": true, "show_sync_tooltip": true, "log_to_file": false }

HTTP Server Toggle

The http_enabled setting controls whether the local HTTP server runs. When set to false, the HTTP server won't start — only the tunnel transport is available. Default is true.

{

"http_enabled": false }

This is useful if you only use the tunnel and don't want a local HTTP server listening.

Tools Menu Item

The *AnkiMCP Server Settings…* entry in Anki's *Tools* menu is shown by default. Set show_settings_menu_item to false to hide it (takes effect after an Anki restart).

{

"show_settings_menu_item": false }

Note: if you hide the menu item and the toolbar indicator, there's no in-app way left to open the settings dialog — you can still edit the config via *Tools → Add-ons → AnkiMCP Server → Config*.

Toolbar Status Indicator

A persistent ● AnkiMCP item in Anki's top toolbar shows tunnel connection state (grey = off, amber = connecting, green = connected); clicking it opens the settings dialog. It's shown by default. Set show_toolbar_indicator to false to hide it (takes effect after an Anki restart).

{

"show_toolbar_indicator": false }

Sync Tooltip

When an AI client triggers a sync, the addon shows a brief, non-modal tooltip in Anki's UI as the sync starts and finishes (e.g. AnkiMCP: syncing…, AnkiMCP: sync complete). This is the only visual cue for these otherwise-silent background syncs. It's shown by default. Set show_sync_tooltip to false to suppress it.

{

"show_sync_tooltip": false }

Diagnostic File Logging

Set log_to_file to true to write a rotating log to user_files/ankimcp.log (~1 MB per file, 3 backups). It's off by default. When enabled, the addon records a startup diagnostics snapshot (addon/Anki/Qt/Python versions plus the live provenance of shared libraries like pydantic, mcp, protobuf, etc.), which is the key data for diagnosing cross-add-on conflicts. Secrets — the http_api_key, OAuth tokens, and any Bearer token — are redacted before anything is written to disk.

{

"log_to_file": true }

The settings dialog (*Tools → AnkiMCP Server Settings…*) has an Open log folder button and a Copy diagnostics button (the same snapshot, formatted for pasting into a forum post). Takes effect after an Anki restart.

Disabli