Anki MCP Server

v1.0.0community

MCP server for Anki flashcards: adaptive review, notes, media, and deck management via AnkiConnect.

mcpnpm

Install

agent-store add ankimcp-anki-mcp-server

将运行命令：npx -y @ankimcp/anki-mcp-server

README

Anki MCP Server

<div align="center"> <img src="./docs/images/ankimcp.png" alt="Anki + MCP Integration" width="600" /> <p><strong>Seamlessly integrate <a href="https://apps.ankiweb.net">Anki</a> with AI assistants through the <a href="https://modelcontextprotocol.io">Model Context Protocol</a></strong></p> </div>

Beta - This project is in active development. APIs and features may change.

A Model Context Protocol (MCP) server that enables AI assistants to interact with Anki, the spaced repetition flashcard application.

Transform your Anki experience with natural language interaction - like having a private tutor. The AI assistant doesn't just present questions and answers; it can explain concepts, make the learning process more engaging and human-like, provide context, and adapt to your learning style. It can create and edit notes on the fly, turning your study sessions into dynamic conversations. More features coming soon!

Examples and Tutorials

For comprehensive guides, real-world examples, and step-by-step tutorials on using this MCP server with Claude Desktop, visit:

ankimcp.ai - Complete documentation with practical examples and use cases

See docs/ for supplementary documentation, including the reviewer setup guide and the sample Anki deck.

Example Use Cases

Three representative prompts showing the tool flows this server enables:

"Help me review my Spanish deck." — The assistant syncs with AnkiWeb (sync), fetches due cards (get_due_cards with deck filter), presents each card (present_card), and records your rating (rate_card). Natural study conversation with explanations tailored to you.
"Create 10 Arabic vocab cards with RTL styling." — The assistant lists note types (modelNames), creates a custom RTL model if needed (createModel + updateModelStyling for right-to-left CSS), then batch-creates the cards (addNotes).
"Import this image from my Downloads folder into the front of the selected note." — The assistant uploads the local file (storeMediaFile with a file path), reads the currently-selected note from the browser (guiSelectedNotes + notesInfo), and updates the front field with an <img> tag (updateNoteFields).

Available Tools

The server exposes 42 MCP tools — 31 essential tools for everyday Anki operations and 11 GUI tools that drive the Anki desktop interface for note editing/creation workflows.

Essential Tools

Review & Study

sync - Sync with AnkiWeb to pull latest data and push changes
get_due_cards - Get cards that are due for review, optionally filtered by deck
get_cards - Get cards with flexible filtering by state (due, new, learning, suspended, buried) and deck
present_card - Show a card for review with its question/front side
rate_card - Rate card performance (Again, Hard, Good, Easy) and schedule the next review

Deck Management

listDecks - List all decks, optionally with per-deck card-count statistics
deckStats - Get comprehensive statistics for a single deck (counts, ease/interval distributions)
createDeck - Create a new empty deck (supports Parent::Child, max 2 levels)
changeDeck - Move cards to a different deck (created if it doesn't exist)

Note Management

addNote - Create a single note with specified fields and tags
addNotes - Batch-create up to 100 notes sharing a deck and model (partial success supported)
findNotes - Search for notes using Anki query syntax (deck:, tag:, is:due, etc.)
notesInfo - Get detailed information about notes (fields, tags, CSS styling)
updateNoteFields - Update existing note fields (CSS-aware, supports HTML content)
deleteNotes - Delete notes and all associated cards (destructive, requires confirmation)

Tag Management

getTags - Get all tags in the collection (use first to avoid duplication)
addTags - Add space-separated tags to specified notes
removeTags - Remove space-separated tags from specified notes
replaceTags - Rename a tag across specified notes
clearUnusedTags - Remove orphaned tags not used by any notes (destructive)

Media Management

getMediaFilesNames - List media files in collection.media, optionally filtered by pattern
retrieveMediaFile - Download a media file as base64 content
storeMediaFile - Upload media from base64 data, an absolute file path, or a URL
deleteMediaFile - Remove a media file from collection.media (destructive)

💡 Best Practice for Images:

✅ Use file paths (e.g., /Users/you/image.png) - Fast and efficient
✅ Use URLs (e.g., https://example.com/image.jpg) - Direct download
❌ Avoid base64 - Extremely slow and token-inefficient

Just tell Claude where the image is, and it will handle the upload automatically using the most efficient method.

Model/Template Management

modelNames - List all available note types/models
modelFieldNames - Get field names for a specific note type
modelStyling - Get CSS styling information for a note type
modelTemplates - Get the card templates (Front and Back HTML) for a note type
createModel - Create a new note type with custom fields, card templates, and CSS (e.g., RTL models)
updateModelStyling - Update the CSS styling for an existing note type (applies to all its cards)
updateModelTemplates - Update the card templates (Front and Back HTML) for an existing note type (applies to all its cards)
addModelField - Add a new field to an existing note type (appended at the end or inserted at a specific position)
removeModelField - Remove a field from an existing note type (deletes its content from all notes; requires explicit confirmation)
renameModelField - Rename a field in an existing note type (card templates referencing the old name must be updated separately)
repositionModelField - Change the position of a field within an existing note type

Statistics

collection_stats - Aggregated statistics across all decks with per-deck breakdown
review_stats - Review history analysis (temporal patterns, retention metrics, study streaks)

GUI Tools

Tools that drive the Anki desktop interface. Intended for note editing/creation and deck-management workflows, not for review sessions.

guiBrowse - Open the Card Browser and search for cards
guiSelectCard - Select a specific card in the Card Browser
guiSelectedNotes - Get IDs of notes currently selected in the Card Browser
guiAddCards - Open the Add Cards dialog with preset note details
guiEditNote - Open the note editor for a specific note
guiDeckOverview - Open the Deck Overview dialog for a specific deck
guiDeckBrowser - Open the Deck Browser dialog
guiCurrentCard - Get info about the current card in review mode
guiShowQuestion - Show the question side of the current card
guiShowAnswer - Show the answer side of the current card
guiUndo - Undo the last action in Anki

Prerequisites

Anki with AnkiConnect plugin installed
Node.js 22.12.0+

Installation

There are a few ways to get the server onto your machine. Once it's installed, head to Connecting an AI Client to wire it up to your AI assistant — locally or remotely.

npm (global or npx)

The general-purpose way to install the server, suitable for any MCP client that launches it directly.

Install it globally for clients that run the ankimcp command:

npm install -g @ankimcp/anki-mcp-server

Or run it on demand with no install required:

npx @ankimcp/anki-mcp-server

MCPB Bundle (Recommended for Claude Desktop)

The easiest way to install this MCP server for Claude Desktop:

Download the latest .mcpb bundle from the Releases page
In Claude Desktop, install the extension:
- Method 1: Go to Settings → Extensions, then drag and drop the .mcpb file
- Method 2: Go to Settings → Developer → Extensions → Install Extension, then select the .mcpb file
Configure AnkiConnect URL if needed (defaults to http://localhost:8765)
Restart Claude Desktop

That's it! The bundle includes everything needed to run the server locally.

For Anthropic MCP Directory reviewers: a zero-to-integration walkthrough with a pre-populated sample deck lives in docs/reviewer-setup.md.

Install from Source (for development)

For development or advanced usage:

npm install
npm run build

Connecting an AI Client

There are two ways an AI assistant can reach this server, depending on where the assistant runs:

Local — the server runs on the same machine as the AI client (Claude Desktop, Cursor, Cline, Zed, or a local browser session). Use STDIO for desktop MCP clients, HTTP for local web-based tools.
Remote — a hosted/remote AI (e.g. ChatGPT or Claude.ai in the cloud) needs to reach the Anki running on your local machine. Use the managed Tunnel (✅ recommended — authenticated) or, as a lighter-weight unauthenticated alternative, ngrok.

Local

The server runs on the same computer as your AI client and talks to AnkiConnect on localhost.

STDIO (primary local integration)

STDIO is the standard transport for local desktop MCP clients — Claude Desktop, Cursor IDE, Cline, Zed Editor, and others. The client launches the server as a subprocess and communicates over standard input/output.

Supported Clients:

Claude Desktop
Cursor IDE - AI-powered code editor
Cline - VS Code extension for AI assistance
Zed Editor - Fast, modern code editor
Other MCP clients that support STDIO transport

For Claude Desktop, the MCPB bundle is the easiest path. For other clients, configure the npm package with the --stdio flag.

Configuration - Choose one method:

Method 1: Using npx (recommended - no installation needed)

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Method 2: Using global installation

First, install globally:

npm install -g @ankimcp/anki-mcp-server

Then configure:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Configuration file locations:

Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)
Cline: Accessible via settings UI in VS Code
Zed Editor: Install as MCP extension through extension marketplace

For client-specific features and troubleshooting, consult your MCP client's documentation. See also Connect to Claude Desktop for a config that points directly at a built dist/main-stdio.js.

HTTP (local web-based AI)

HTTP mode runs the server as a local web server speaking the MCP Streamable HTTP protocol. It's the transport a web-based AI tool talks to when pointed at your machine, and it's also what the Remote options expose to the outside world. On its own, HTTP mode binds to localhost only.

Binding beyond localhost? If you pass --host 0.0.0.0 (or run behind a reverse proxy/public domain), the server only accepts loopback Host headers by default for DNS-rebinding protection — set ALLOWED_HOSTS to the hostname(s) clients use. See HTTP Mode Configuration.

Setup - Choose one method:

Method 1: Using npx (recommended - no installation needed)

# Quick start
npx @ankimcp/anki-mcp-server

# With custom options
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765

Method 2: Using global installation

# Install once
npm install -g @ankimcp/anki-mcp-server

# Run the server
ankimcp

# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765

Method 3: Install from source (for development)

npm install
npm run build
npm run start:prod:http

To make a local HTTP server reachable by a cloud-hosted AI, use one of the Remote options below.

Remote

A hosted/remote AI (such as ChatGPT or Claude.ai running in the cloud) can't reach localhost directly. These options expose your local Anki to the internet so a remote assistant can talk to it.

Tunnel (✅ Recommended)

Recommended remote path — authenticated & secure. Unlike a raw public port, tunnel mode requires you to log in (OAuth 2.0 device flow), so the endpoint isn't open to anyone who guesses the URL.

Tunnel mode lets web-based AI assistants reach your local Anki without running your own tunnel. The server connects out to the managed AnkiMCP tunnel service (wss://tunnel.ankimcp.ai) over a WebSocket and is assigned a public URL. Authentication is built in — no ngrok account or separate tunnel process required, and you log in once.

Log in (OAuth device flow):

Tunnel mode uses the OAuth 2.0 Device Authorization Grant. Logging in opens your browser automatically to an approval page with the code already embedded in the URL — nothing to type, just approve. (If the browser can't open, the terminal prints a verification URL and code to enter manually as a fallback.) On success, credentials are saved to ~/.ankimcp/credentials.json (file permissions 0600).

# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
ankimcp --login
npx @ankimcp/anki-mcp-server --login

# Clear saved credentials
ankimcp --logout

Start the tunnel:

# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
ankimcp --tunnel
npx @ankimcp/anki-mcp-server --tunnel

# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
ankimcp --tunnel wss://my-tunnel.example.com

If no credentials exist, --tunnel automatically starts the login flow first, then continues to the tunnel. This auto-login requires an interactive terminal — when stdout is not a TTY (systemd, headless Docker, CI), the server fast-fails and asks you to run ankimcp --login first. Once connected, the public tunnel URL is printed; press Ctrl+C to disconnect. Share that URL with your AI assistant.

Tunnel-mode environment variables:

Variable	Description	Default
`TUNNEL_SERVER_URL`	Tunnel server WebSocket URL (the `--tunnel`/`--login` flag value overrides this)	`wss://tunnel.ankimcp.ai`
`TUNNEL_AUTH_CLIENT_ID`	OAuth client ID for the device flow. Advanced — only needed when pointing at a self-hosted tunnel/auth service.	(built-in)

The device-flow auth endpoints (/auth/device, /auth/token) are derived from TUNNEL_SERVER_URL, so pointing --tunnel (or TUNNEL_SERVER_URL) at a different host also moves authentication to that host.

How it works: Tunnel mode runs the MCP server in-process behind an in-memory transport (McpModule is started with no built-in transport). TunnelMcpService connects that in-memory transport to the MCP server, and TunnelClient bridges it to the remote tunnel service over a WebSocket — relaying MCP requests in and responses out. AnkiConnect is still only ever reached on your local machine.

ngrok (unauthenticated alternative)

If you'd rather expose local HTTP mode publicly without an account on the managed tunnel, the built-in --ngrok flag launches an ngrok subprocess (src/services/ngrok.service.ts) and prints the public URL in the startup banner:

# One-time ngrok setup, then:
ankimcp --ngrok

This route is unauthenticated — anyone with the URL can reach your Anki, so it's less secure than Tunnel. Prefer Tunnel unless you have a specific reason to manage your own ngrok endpoint. (Requires a global ngrok install and authtoken.)

The --ngrok flag launches ngrok with --host-header=rewrite, so ngrok rewrites the upstream Host to localhost before forwarding. That keeps requests within the loopback Host allowlist (see DNS-rebinding protection) without you having to add the public *.ngrok domain to ALLOWED_HOSTS. If you instead run ngrok manually, use the same flag — ngrok http --host-header=rewrite 3000 — otherwise ngrok forwards the public ngrok hostname as Host and the server rejects it with 403.

CLI Options (all modes)

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -p, --port <port>              Port to listen on (HTTP mode, default: 3000)
  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks all write operations)
  --help                         Show help message

Usage with npx (no installation needed):
  npx @ankimcp/anki-mcp-server                        # HTTP mode
  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
  npx @ankimcp/anki-mcp-server --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

Usage with global installation:
  npm install -g @ankimcp/anki-mcp-server             # Install once
  ankimcp                                             # HTTP mode
  ankimcp --port 8080                                 # Custom port
  ankimcp --stdio                                     # STDIO mode
  ankimcp --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

Read-Only Mode (all modes)

The --read-only flag prevents any modifications to your Anki collection. When enabled:

All read operations work normally (browsing decks, viewing cards, searching notes)
Review operations are allowed (sync, answerCards, suspend/unsuspend)
Content modifications are blocked (addNote, deleteNotes, createDeck, updateNoteFields, etc.)
Useful for safely exploring Anki data without risk of accidental changes

# HTTP mode with read-only
ankimcp --read-only

# STDIO mode with read-only
ankimcp --stdio --read-only

# Can combine with other flags
ankimcp --ngrok --read-only

You can also enable read-only mode via environment variable:

READ_ONLY=true ankimcp

Or in MCP client configuration:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",

版本历史

v1.0.0latest7/7/2026

用户评价

暂无评价

登录后可发表评价。