🚀 Anki MCP Server
Seamlessly integrate Anki with AI assistants through the Model Context Protocol
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!
🚀 Quick Start
Prerequisites
Installation
This server works in two modes:
- Local mode (STDIO) - For Claude Desktop on your computer (recommended for most users)
- Remote mode (HTTP) - For web - based AI assistants like ChatGPT or Claude.ai
Option 1: MCPB Bundle (Recommended - Local Mode)
- 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
Option 2: NPM Package with STDIO (For Other MCP Clients)
Supported Clients:
- 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
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"
}
}
}
}
Option 3: HTTP Mode (For Remote AI Assistants)
How it works (simple explanation):
- You run a small server on your computer (where Anki is installed)
- Use the built - in
--ngrok flag to automatically create a public tunnel URL
- Share that URL with ChatGPT or Claude.ai
- Now the AI can talk to your Anki through the internet!
New 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)
npx @ankimcp/anki-mcp-server
npx @ankimcp/anki-mcp-server --ngrok
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
npm install -g @ankimcp/anki-mcp-server
ankimcp
ankimcp --ngrok
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
Option 4: Manual Installation from Source (Local Mode)
For development or advanced usage:
npm install
npm run build
Connect to Claude Desktop (Local Mode)
You can configure the server in Claude Desktop by either:
- Going to: Settings → Developer → Edit Config
- Or manually editing the config file
Configuration
Add the following to your Claude Desktop config:
{
"mcpServers": {
"anki-mcp": {
"command": "node",
"args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
"env": {
"ANKI_CONNECT_URL": "http://localhost:8765"
}
}
}
}
Replace /path/to/anki-mcp-server with your actual project path.
Config File Locations
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
For more details, see the official MCP documentation.
✨ Features
Review & Study
sync - Sync with AnkiWeb
get_due_cards - Get cards for review
present_card - Show card for review
rate_card - Rate card performance
Deck Management
list_decks - Show available decks
createDeck - Create new decks
Note Management
addNote - Create new notes
findNotes - Search for notes using Anki query syntax
notesInfo - Get detailed information about notes (fields, tags, CSS)
updateNoteFields - Update existing note fields (CSS - aware, supports HTML)
deleteNotes - Delete notes and their cards
Media Management
mediaActions - Manage media files (audio/images)
storeMediaFile - Upload media from base64 data, file paths, or URLs
retrieveMediaFile - Download media as base64
getMediaFilesNames - List media files with optional pattern filtering
deleteMediaFile - Remove media files
💡 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
Model/Template Management
modelNames - List note types
modelFieldNames - Get fields for a note type
modelStyling - Get CSS styling for a note type
💻 Usage Examples
Searching and Updating Notes
# 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)
Anki Query Syntax Examples
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 deck
📚 Documentation
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
Environment Variables (Optional)
| Property |
Details |
ANKI_CONNECT_URL |
AnkiConnect URL |
ANKI_CONNECT_API_VERSION |
API version |
ANKI_CONNECT_API_KEY |
API key if configured in AnkiConnect |
ANKI_CONNECT_TIMEOUT |
Request timeout in ms |
Important Notes
CSS and HTML Handling
- The
notesInfo tool returns CSS styling information for proper rendering awareness
- The
updateNoteFields tool supports HTML content in fields and preserves CSS styling
- Each note model has its own CSS styling - use
modelStyling to get model - specific CSS
Update Warning
⚠️ Important Note
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. See Known Issues for more details.
Deletion Safety
The deleteNotes tool requires explicit confirmation (confirmDeletion: true) to prevent accidental deletions. Deleting a note removes ALL associated cards permanently.
Known Issues
For a comprehensive list of known issues and limitations, please visit our documentation:
Known Issues Documentation
Critical Limitations
⚠️ Important Note
When updating notes using updateNoteFields, the update will silently fail if the note is currently being viewed in Anki's browser window. This is an upstream AnkiConnect limitation.
Workaround: Always close the browser or navigate to a different note before updating.
Development
Transport Modes
This server supports two MCP transport modes via separate entry points:
- STDIO Mode (Default):
- For local MCP clients like Claude Desktop
- Uses standard input/output for communication
- Entry point:
dist/main-stdio.js
- Run:
npm run start:prod:stdio or node dist/main-stdio.js
- MCPB bundle: Uses STDIO mode
- HTTP Mode (Streamable HTTP):
- For remote MCP clients and web - based integrations
- Uses MCP Streamable HTTP protocol
- Entry point:
dist/main-http.js
- Run:
npm run start:prod:http or node dist/main-http.js
- Default port: 3000 (configurable via
PORT env var)
- Default host:
127.0.0.1 (configurable via HOST env var)
- MCP endpoint:
http://127.0.0.1:3000/ (root path)
Building
npm run build
HTTP Mode Configuration
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:
- Origin header validation (prevents DNS rebinding attacks)
- Binds to localhost (127.0.0.1) by default
- No authentication in current version (OAuth support planned)
Example: Running Modes
npm run start:dev:stdio
npm run start:dev:http
npm run start:prod:stdio
node dist/main-stdio.js
npm run start:prod:http
PORT=8080 HOST=0.0.0.0 node dist/main-http.js
Building an MCPB Bundle
To create a distributable MCPB bundle:
npm run mcpb:bundle
This command will:
- Sync version from
package.json to manifest.json
- Remove old
.mcpb files
- Build the TypeScript project
- Package
dist/ and node_modules/ into an .mcpb file
- Run
mcpb clean to remove devDependencies (optimizes bundle from ~47MB to ~10MB)
The output file will be named anki-mcp-server-X.X.X.mcpb and can be distributed for one - click installation.
What Gets Bundled
The MCPB package includes:
- Compiled JavaScript (
dist/ directory - includes both entry points)
- Production dependencies only (
node_modules/ - devDependencies removed by mcpb clean)
- Package metadata (
package.json)
- Manifest configuration (
manifest.json - configured to use main-stdio.js)
- Icon (
icon.png)
Source files, tests, and development configs are automatically excluded via .mcpbignore.
Logging in Claude Desktop
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:
- main.log - General Claude Desktop application logs
- mcp-server-Anki MCP Server.log - MCP protocol messages for this extension
- mcp.log - Combined MCP logs from all servers
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:
- Application startup and MCP protocol communication → MCP - specific log
- Server internal logging (pino) → Both MCP - specific log and sometimes main.log
To view logs in real - time:
tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log
Debugging the MCP Server
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.
Step 1: Configure Debug Server in MCP Inspector
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"
}
}
}
Step 2: Start the Debug Server
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.
Step 3: Attach Debugger from Your IDE
- WebStorm:
- Go to Run → Edit Configurations
- Add a new Attach to Node.js/Chrome configuration
- Set the port to
9229
- Click Debug to attach
- VS Code:
- Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
- Select Debug MCP Server (Attach) configuration
- Press F5 to attach
Step 4: Set Breakpoints and Debug
Once attached, you can:
- Set breakpoints in your TypeScript source files
- Step through code execution
- Inspect variables and call stack
- Use the debug console for evaluating expressions
The debugger will work with source maps, allowing you to debug the original TypeScript code rather than the compiled JavaScript.
Debugging with Claude Desktop
You can also debug the MCP server while it runs inside Claude Desktop by enabling the Node.js debugger and attaching your IDE.
Step 1: Configure Claude Desktop for Debugging
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",
"<path_to_project>/anki-mcp-server/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)
Step 2: Restart Claude Desktop
After saving the config, restart Claude Desktop. The MCP server will now run with debugging enabled on port 9229.
Step 3: Attach Debugger from Your IDE
- WebStorm:
- Go to Run → Edit Configurations
- Click the + button and select Attach to Node.js/Chrome
- Configure:
- Name:
Attach to Anki MCP (Claude Desktop)
- Host:
localhost
- Port:
9229
- Attach to:
Node.js < 8 or Chrome or Node.js > 6.3 (depending on WebStorm version)
- Click OK
- Click Debug (Shift+F9) to attach
- VS Code:
- Add to
.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"]
}
]
}
- Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
- Select Attach to Anki MCP (Claude Desktop)
- Press F5 to attach
Step 4: Debug in Real - Time
Once attached, you can:
- Set breakpoints in your TypeScript source files (e.g.,
src/mcp/primitives/essential/tools/create-model.tool.ts)
- Use Claude Desktop normally - breakpoints will hit when tools are invoked
- Step through code execution
- Inspect variables and call stack
- Use the debug console
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.
Build Commands
npm run build
npm run start:dev:stdio
npm run start:dev:http
npm run type-check
npm run lint
npm run mcpb:bundle
NPM Package Testing (Local)
Test the npm package locally before publishing:
npm run pack:local
npm run install:local
ankimcp
npm run uninstall:local
Testing Commands
npm test
npm run test:unit
npm run test:tools
npm run test:workflows
npm run test:e2e
npm run test:cov
npm run test:watch
npm run test:debug
npm run test:ci
Test Coverage
The project maintains 70% minimum coverage thresholds for:
- Branches
- Functions
- Lines
- Statements
Coverage reports are generated in the coverage/ directory.
Versioning
This project follows Semantic Versioning with a pre - 1.0 development approach:
- 0.x.x - Beta/Development versions (current phase)
- 0.1.x - Bug fixes and patches
- 0.2.0+ - New features or minor improvements
- Breaking changes are acceptable in 0.x versions
- 1.0.0 - First stable release
- Will be released when the API is stable and tested
- Breaking changes will require major version bumps (2.0.0, etc.)
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.
Similar Projects
If you're exploring Anki MCP integrations, here are other projects in this space:
- scorzeth/anki-mcp-server:
- Status: Appears to be abandoned (no recent updates)
- Early implementation of Anki MCP integration
- nailuoGG/anki-mcp-server:
- Approach: Lightweight, single - file implementation
- Architecture: Procedural code structure with all tools in one file
- Good for: Simple use cases, minimal dependencies
Why this project differs:
- Enterprise - grade architecture: Built on NestJS with dependency injection
- Modular design: Each tool is a separate class with clear separation of concerns
- Maintainability: Easy to extend with new features without touching existing code
- Testing: Comprehensive test suite with 70% coverage requirement
- Type safety: Strict TypeScript with Zod validation
- Error handling: Robust error handling with helpful user feedback
- Production - ready: Proper logging, progress reporting, and MCPB bundle support
- Scalability: Can easily grow from basic tools to complex workflows
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.
Useful Links
📄 License
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL - 3.0 - or - later).
Why AGPL - 3.0?
This license was chosen to maintain compatibility with Anki's AGPL - 3.0 license for potential future integration scenarios.
What this means:
- Personal use: Use the software freely
- Running as a service for others: You must provide source code access (AGPL Section 13)
- Modifying and distributing: Share your improvements under AGPL - 3.0 - or - later
For complete license terms, see the LICENSE file.
Third - Party Attributions
- Anki® is a registered trademark of Ankitects Pty Ltd. This project is an unofficial third - party tool and is not affiliated with, endorsed by, or sponsored by Ankitects Pty Ltd. The Anki logo is used under the alternative license for referencing Anki with a link to https://apps.ankiweb.net. For the official Anki application, visit https://apps.ankiweb.net.
- Model Context Protocol (MCP) is an open standard by Anthropic. The MCP logo is from the official MCP documentation repository and is used under the MIT License. For more information about MCP, visit https://modelcontextprotocol.io.
- This is an independent project that bridges Anki and MCP technologies. All trademarks, service marks, trade names, product names, and logos are the property of their respective owners.