Anki
STDIOMCP server enabling AI assistants to interact with Anki flashcard application using natural language
MCP server enabling AI assistants to interact with Anki flashcard application using natural language
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!
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
sync - Sync with AnkiWebget_due_cards - Get cards for reviewpresent_card - Show card for reviewrate_card - Rate card performancelist_decks - Show available deckscreateDeck - Create new decksaddNote - Create new notesfindNotes - Search for notes using Anki query syntaxnotesInfo - Get detailed information about notes (fields, tags, CSS)updateNoteFields - Update existing note fields (CSS-aware, supports HTML)deleteNotes - Delete notes and their cardsmediaActions - Manage media files (audio/images)
storeMediaFile - Upload media from base64 data, file paths, or URLsretrieveMediaFile - Download media as base64getMediaFilesNames - List media files with optional pattern filteringdeleteMediaFile - Remove media filesmodelNames - List note typesmodelFieldNames - Get fields for a note typemodelStyling - Get CSS styling for a note typeThis server works in two modes:
The easiest way to install this MCP server for Claude Desktop:
.mcpb bundle from the Releases page.mcpb file.mcpb filehttp://localhost:8765)That's it! The bundle includes everything needed to run the server locally.
Want to use Anki with MCP clients like Cursor IDE, Cline, or Zed Editor? Use the npm package with the --stdio flag:
Supported Clients:
Configuration - Choose one method:
Method 1: Using npx (recommended - no installation needed)
{ "mcpServers": { "anki-mcp": { "command": "npx", "args": ["-y", "anki-mcp-http", "--stdio"], "env": { "ANKI_CONNECT_URL": "http://localhost:8765" } } } }
Method 2: Using global installation
First, install globally:
npm install -g anki-mcp-http
Then configure:
{ "mcpServers": { "anki-mcp": { "command": "anki-mcp-http", "args": ["--stdio"], "env": { "ANKI_CONNECT_URL": "http://localhost:8765" } } } }
Configuration file locations:
~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)For client-specific features and troubleshooting, consult your MCP client's documentation.
Want to use Anki with ChatGPT or Claude.ai in your browser? This mode lets you connect web-based AI tools to your local Anki.
How it works (simple explanation):
--ngrok flag to automatically create a public tunnel URLNew in v0.8.0: Integrated ngrok support with the --ngrok flag - no need to run ngrok separately!
Setup - Choose one method:
Method 1: Using npx (recommended - no installation needed)
# Quick start npx anki-mcp-http # With ngrok tunnel (recommended for web-based AI) npx anki-mcp-http --ngrok # With custom options npx anki-mcp-http --port 8080 --host 0.0.0.0 npx anki-mcp-http --anki-connect http://localhost:8765
Method 2: Using global installation
# Install once npm install -g anki-mcp-http # Run the server anki-mcp-http # With ngrok tunnel (recommended for web-based AI) anki-mcp-http --ngrok # With custom options anki-mcp-http --port 8080 --host 0.0.0.0 anki-mcp-http --anki-connect http://localhost:8765
Method 3: Install from source (for development)
npm install npm run build npm run start:prod:http
CLI Options:
anki-mcp-http [options] Options: --stdio Run in STDIO mode (for MCP clients) -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) --help Show help message Usage with npx (no installation needed): npx anki-mcp-http # HTTP mode npx anki-mcp-http --port 8080 # Custom port npx anki-mcp-http --stdio # STDIO mode npx anki-mcp-http --ngrok # HTTP mode with ngrok tunnel Usage with global installation: npm install -g anki-mcp-http # Install once anki-mcp-http # HTTP mode anki-mcp-http --port 8080 # Custom port anki-mcp-http --stdio # STDIO mode anki-mcp-http --ngrok # HTTP mode with ngrok tunnel
Using with ngrok:
Method 1: Integrated (Recommended - One Command)
# One-time setup (if you haven't already): npm install -g ngrok ngrok config add-authtoken <your-token> # Get token from https://dashboard.ngrok.com # Start server with ngrok tunnel in one command: anki-mcp-http --ngrok # The tunnel URL will be displayed in the startup banner # Example output: # 🌐 Ngrok tunnel: https://abc123.ngrok-free.app
Method 2: Manual (Two Terminals)
# Terminal 1: Start the server anki-mcp-http # Terminal 2: Create tunnel ngrok http 3000 # Copy the ngrok URL (looks like: https://abc123.ngrok-free.app) # Share this URL with your AI assistant
Benefits of --ngrok flag:
anki-mcp-http --port 8080 --ngrokSecurity note: Anyone with your ngrok URL can access your Anki, so keep that URL private!
For development or advanced usage:
npm install npm run build
You can configure the server in Claude Desktop by either:
Add the following to your Claude Desktop config:
{ "mcpServers": { "anki-mcp": { "command": "node", "args": ["/path/to/anki-mcp-desktop/dist/main-stdio.js"], "env": { "ANKI_CONNECT_URL": "http://localhost:8765" } } } }
Replace /path/to/anki-mcp-desktop with your actual project path.
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonFor more details, see the official MCP documentation.
| Variable | Description | Default |
|---|---|---|
ANKI_CONNECT_URL | AnkiConnect URL | http://localhost:8765 |
ANKI_CONNECT_API_VERSION | API version | 6 |
ANKI_CONNECT_API_KEY | API key if configured in AnkiConnect | - |
ANKI_CONNECT_TIMEOUT | Request timeout in ms | 5000 |
# Search for notes in a specific deck
findNotes(query: "deck:Spanish")
# Get detailed information about notes
notesInfo(notes: [1234567890, 1234567891])
# Update a note's fields (HTML content supported)
updateNoteFields(note: {
id: 1234567890,
fields: {
"Front": "<b>¿Cómo estás?</b>",
"Back": "How are you?"
}
})
# Delete notes (requires confirmation)
deleteNotes(notes: [1234567890], confirmDeletion: true)
The findNotes tool supports Anki's powerful query syntax:
"deck:DeckName" - All notes in a specific deck"tag:important" - Notes with the "important" tag"is:due" - Cards that are due for review"is:new" - New cards that haven't been studied"added:7" - Notes added in the last 7 days"front:hello" - Notes with "hello" in the front field"flag:1" - Notes with red flag"prop:due<=2" - Cards due within 2 days"deck:Spanish tag:verb" - Spanish deck notes with verb tag (AND)"deck:Spanish OR deck:French" - Notes from either decknotesInfo tool returns CSS styling information for proper rendering awarenessupdateNoteFields tool supports HTML content in fields and preserves CSS stylingmodelStyling to get model-specific CSS⚠️ IMPORTANT: When using updateNoteFields, do NOT view the note in Anki's browser while updating, or the fields will not update properly. Close the browser or switch to a different note before updating.
The deleteNotes tool requires explicit confirmation (confirmDeletion: true) to prevent accidental deletions. Deleting a note removes ALL associated cards permanently.
This server supports two MCP transport modes via separate entry points:
dist/main-stdio.jsnpm run start:prod:stdio or node dist/main-stdio.jsdist/main-http.jsnpm run start:prod:http or node dist/main-http.jsPORT env var)127.0.0.1 (configurable via HOST env var)http://127.0.0.1:3000/ (root path)npm run build # Builds once, creates dist/ with both entry points
Both main-stdio.js and main-http.js are in the same dist/ directory. Choose which to run based on your needs.
Environment Variables:
PORT - HTTP server port (default: 3000)HOST - Bind address (default: 127.0.0.1 for localhost-only)ALLOWED_ORIGINS - Comma-separated list of allowed origins for CORS (default: localhost)LOG_LEVEL - Logging level (default: info)Security:
Example: Running Modes
# Development - STDIO mode (watch mode with auto-rebuild) npm run start:dev:stdio # Development - HTTP mode (watch mode with auto-rebuild) npm run start:dev:http # Production - STDIO mode npm run start:prod:stdio # or node dist/main-stdio.js # Production - HTTP mode npm run start:prod:http # or PORT=8080 HOST=0.0.0.0 node dist/main-http.js
To create a distributable MCPB bundle:
npm run mcpb:bundle
This command will:
package.json to manifest.json.mcpb filesdist/ and node_modules/ into an .mcpb fileThe output file will be named based on the current version (e.g., anki-mcp-http-0.5.0.mcpb) and can be distributed for one-click installation.
The MCPB package includes:
dist/ directory - includes both entry points)node_modules/)package.json)manifest.json - configured to use main-stdio.js)icon.png)Source files, tests, and development configs are automatically excluded via .mcpbignore.
When running as an MCPB extension in Claude Desktop, logs are written to:
Log Location: ~/Library/Logs/Claude/ (macOS)
The logs are split across multiple files:
Note: The pino logger output (INFO, ERROR, WARN messages from the server code) goes to stderr and appears in the MCP-specific log files. Claude Desktop determines which log file receives which messages, but generally:
To view logs in real-time:
tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log
You can debug the MCP server using the MCP Inspector and attaching a debugger from your IDE (WebStorm, VS Code, etc.).
Note for HTTP Mode: When testing HTTP mode (Streamable HTTP) with MCP Inspector, use "Connection Type: Via Proxy" to avoid CORS errors.
The mcp-inspector-config.json already includes a debug server configuration:
{ "mcpServers": { "stdio-server-debug": { "type": "stdio", "command": "node", "args": ["--inspect-brk=9229", "dist/main-stdio.js"], "env": { "MCP_SERVER_NAME": "anki-mcp-stdio-debug", "MCP_SERVER_VERSION": "1.0.0", "LOG_LEVEL": "debug" }, "note": "Anki MCP server with debugging enabled on port 9229" } } }
Run the MCP Inspector with the debug server:
npm run inspector:debug
This will start the server with Node.js debugging enabled on port 9229 and pause execution at the first line.
9229Once attached, you can:
The debugger will work with source maps, allowing you to debug the original TypeScript code rather than the compiled JavaScript.
You can also debug the MCP server while it runs inside Claude Desktop by enabling the Node.js debugger and attaching your IDE.
Update your Claude Desktop config to enable debugging:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{ "mcpServers": { "anki-mcp": { "command": "node", "args": [ "--inspect=9229", "/Users/anatoly/Developer/git/anki-mcp-organization/anki-mcp-desktop/dist/main-stdio.js" ], "env": { "ANKI_CONNECT_URL": "http://localhost:8765" } } } }
Key change: Add --inspect=9229 before the path to dist/main-stdio.js
Debug options:
--inspect=9229 - Start debugger immediately, doesn't block (recommended)--inspect-brk=9229 - Pause execution until debugger attaches (for debugging startup issues)After saving the config, restart Claude Desktop. The MCP server will now run with debugging enabled on port 9229.
Attach to Anki MCP (Claude Desktop)localhost9229Node.js < 8 or Chrome or Node.js > 6.3 (depending on WebStorm version).vscode/launch.json:{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "attach", "name": "Attach to Anki MCP (Claude Desktop)", "port": 9229, "skipFiles": ["<node_internals>/**"], "sourceMaps": true, "outFiles": ["${workspaceFolder}/dist/**/*.js"] } ] }
Once attached, you can:
src/mcp/primitives/essential/tools/create-model.tool.ts)Example: Set a breakpoint in create-model.tool.ts at line 119, then ask Claude to create a new model. The debugger will pause at your breakpoint!
Note: The debugger stays attached as long as Claude Desktop is running. You can detach/reattach anytime without restarting Claude Desktop.
npm run build # Build the project (compile TypeScript to JavaScript) npm run start:dev:stdio # STDIO mode with watch (auto-rebuild) npm run start:dev:http # HTTP mode with watch (auto-rebuild) npm run type-check # Run TypeScript type checking npm run lint # Run ESLint npm run mcpb:bundle # Sync version, clean, build, and create MCPB bundle
Test the npm package locally before publishing:
# 1. Create local package npm run pack:local # Builds and creates anki-mcp-http-*.tgz # 2. Install globally from local package npm run install:local # Installs from ./anki-mcp-http-*.tgz # 3. Test the command ankimcp # Runs HTTP server on port 3000 # 4. Uninstall when done testing npm run uninstall:local # Removes global installation
How it works:
npm pack creates a .tgz file identical to what npm publish would create.tgz simulates what users get from npm install -g ankimcpnpm test # Run all tests npm run test:unit # Run unit tests only npm run test:tools # Run tool-specific tests npm run test:workflows # Run workflow integration tests npm run test:e2e # Run end-to-end tests npm run test:cov # Run tests with coverage report npm run test:watch # Run tests in watch mode npm run test:debug # Run tests with debugger npm run test:ci # Run tests for CI (silent, with coverage)
The project maintains 70% minimum coverage thresholds for:
Coverage reports are generated in the coverage/ directory.
This project follows Semantic Versioning with a pre-1.0 development approach:
0.x.x - Beta/Development versions (current phase)
1.0.0 - First stable release
Current Status: 0.8.0 - Active beta development. New features include integrated ngrok tunneling (--ngrok flag), the twenty_rules prompt for evidence-based flashcard creation, media file management, and improved prompt system. APIs may change based on feedback and testing.
If you're exploring Anki MCP integrations, here are other projects in this space:
Why this project (anki-mcp-desktop) differs:
Use case: If you need a solid foundation for building advanced Anki integrations or plan to extend functionality significantly, this project's architectural approach makes it easier to maintain and scale over time.