by ankimcp
Enables AI assistants to interact with Anki for creating, editing, reviewing, and managing flashcards through a Model Context Protocol server.
Anki MCP Desktop provides a Model Context Protocol (MCP) server that lets AI assistants communicate with Anki, the spaced‑repetition flashcard application. It turns natural‑language prompts into actions such as syncing, fetching due cards, adding notes, updating fields, managing media, and more.
npx:
{
"mcpServers": {
"anki-mcp": {
"command": "npx",
"args": ["-y", "anki-mcp-http"],
"env": {"ANKI_CONNECT_URL": "http://localhost:8765"}
}
}
}
--ngrok to expose the server publicly.addNote, findNotes, sync, rate_card) via natural‑language prompts in the AI assistant.sync, get_due_cards, present_card, rate_card.--ngrok) for one‑click public tunneling.Q: Do I need to install the package globally?
A: No. The recommended approach is using npx as shown in the configuration, which runs the latest version without a global install.
Q: How do I expose the server to web‑based assistants?
A: Start the server with the --ngrok flag (e.g., npx anki-mcp-http --ngrok). The tunnel URL will be printed and can be shared with ChatGPT or Claude.ai.
Q: What if I want to run the server on a custom port?
A: Use --port <number> (e.g., npx anki-mcp-http --port 8080). Adjust the client configuration accordingly.
Q: Is authentication supported? A: Current versions do not require authentication, but the server validates origin headers and binds to localhost by default. Future releases may add OAuth.
Q: How do I debug the server?
A: Add Node’s inspector flags in the config (e.g., --inspect=9229) and attach your IDE’s debugger. The README provides detailed steps for both standalone and Claude Desktop debugging.
Q: Can I create an MCPB bundle for easy installation?
A: Yes. Run npm run mcpb:bundle to generate a .mcpb file that can be dragged into Claude Desktop.
⚠️ IMPORTANT: Project Renamed (v0.8.2+)
This project has been renamed and moved:
- Package:
anki-mcp-http→@ankimcp/anki-mcp-server- Commands:
anki-mcp-http→ankimcporanki-mcp-server- Repository:
anki-mcp/anki-mcp-desktop→ankimcp/anki-mcp-serverThe old
anki-mcp-httppackage continues to be published for backward compatibility but is deprecated. Please migrate to the new package.
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 files💡 Best Practice for Images:
/Users/you/image.png) - Fast and efficienthttps://example.com/image.jpg) - Direct downloadJust tell Claude where the image is, and it will handle the upload automatically using the most efficient method.
modelNames - 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", "@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/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 @ankimcp/anki-mcp-server
# With ngrok tunnel (recommended for web-based AI)
npx @ankimcp/anki-mcp-server --ngrok
# 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 ngrok tunnel (recommended for web-based AI)
ankimcp --ngrok
# 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
CLI Options:
ankimcp [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 @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 --ngrok # HTTP mode with ngrok tunnel
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 --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:
ankimcp --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
ankimcp
# 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:
ankimcp --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-server/dist/main-stdio.js"],
"env": {
"ANKI_CONNECT_URL": "http://localhost:8765"
}
}
}
}
Replace /path/to/anki-mcp-server 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. See Known Issues for more details.
The deleteNotes tool requires explicit confirmation (confirmDeletion: true) to prevent accidental deletions. Deleting a note removes ALL associated cards permanently.
For a comprehensive list of known issues and limitations, please visit our documentation:
⚠️ IMPORTANT: 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.
For more details and other known issues, see the full documentation.
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 filemcpb 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.
The MCPB package includes:
dist/ directory - includes both entry points)node_modules/ - devDependencies removed by mcpb clean)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.
WebStorm
9229VS Code
Once 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",
"<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)After saving the config, restart Claude Desktop. The MCP server will now run with debugging enabled on port 9229.
WebStorm
Attach to Anki MCP (Claude Desktop)localhost9229Node.js < 8 or Chrome or Node.js > 6.3 (depending on WebStorm version)VS Code
.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 @ankimcp/anki-mcp-server-*.tgz
# 2. Install globally from local package
npm run install:local # Installs from ./@ankimcp/anki-mcp-server-*.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 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.
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
This license was chosen to maintain compatibility with Anki's AGPL-3.0 license for potential future integration scenarios.
What this means:
For complete license terms, see the LICENSE file.
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.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
by topoteretes
Provides dynamic memory for AI agents through modular ECL (Extract, Cognify, Load) pipelines, enabling seamless integration with graph and vector stores using minimal code.
by basicmachines-co
Enables persistent, local‑first knowledge management by allowing LLMs to read and write Markdown files during natural conversations, building a traversable knowledge graph that stays under the user’s control.
by smithery-ai
Provides read and search capabilities for Markdown notes in an Obsidian vault for Claude Desktop and other MCP clients.
by chatmcp
Summarize chat messages by querying a local chat database and returning concise overviews.
by dmayboroda
Provides on‑premises conversational retrieval‑augmented generation (RAG) with configurable Docker containers, supporting fully local execution, ChatGPT‑based custom GPTs, and Anthropic Claude integration.
by qdrant
Provides a Model Context Protocol server that stores and retrieves semantic memories using Qdrant vector search, acting as a semantic memory layer.
by doobidoo
Provides a universal memory service with semantic search, intelligent memory triggers, OAuth‑enabled team collaboration, and multi‑client support for Claude Desktop, Claude Code, VS Code, Cursor and over a dozen AI applications.
by GreatScottyMac
Provides a project‑specific memory bank that stores decisions, progress, architecture, and custom data, exposing a structured knowledge graph via MCP for AI assistants and IDE tools.