Anki MCP Server

⚠️ 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 → ankimcp or anki-mcp-server

Repository: anki-mcp/anki-mcp-desktop → ankimcp/anki-mcp-server

The old anki-mcp-http package continues to be published for backward compatibility but is deprecated. Please migrate to the new package.

Read more about this change →

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!

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

Available Tools

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

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

Model/Template Management

modelNames - List note types
modelFieldNames - Get fields for a note type
modelStyling - Get CSS styling for a note type

Prerequisites

Anki with AnkiConnect plugin installed
Node.js 20.19.0+

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)

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.

Option 2: NPM Package with STDIO (For Other MCP Clients)

Want to use Anki with MCP clients like Cursor IDE, Cline, or Zed Editor? Use the npm package with the --stdio flag:

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"
      }
    }
  }
}

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.

Option 3: HTTP Mode (For Remote AI Assistants)

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):

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)

# 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:

✅ One command instead of two terminals
✅ Automatic cleanup when you press Ctrl+C
✅ URL displayed directly in the startup banner
✅ Works with custom ports: ankimcp --port 8080 --ngrok

Security note: Anyone with your ngrok URL can access your Anki, so keep that URL private!

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.

Environment Variables (Optional)

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`

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

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: 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

Note Updates Fail When Viewed in Browser

⚠️ 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.

Troubleshooting

ERR_REQUIRE_ESM Error

If you see an error like:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

This means your Node.js version is too old. The server requires Node.js 20.19.0 or later.

Check your version:

node --version

Solution: Update Node.js to version 20.19.0 or later. You can download it from nodejs.org or use a version manager like nvm.

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  # 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.

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

# 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

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              # 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

NPM Package Testing (Local)

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
Installing from .tgz simulates what users get from npm install -g ankimcp
This lets you test the full user experience before publishing to npm

Testing Commands

npm 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)

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 & Attribution

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.

Anki MCP Server

⚠️ 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 → ankimcp or anki-mcp-server

Repository: anki-mcp/anki-mcp-desktop → ankimcp/anki-mcp-server

The old anki-mcp-http package continues to be published for backward compatibility but is deprecated. Please migrate to the new package.

Read more about this change →

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.

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

Available Tools

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

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

Model/Template Management

modelNames - List note types
modelFieldNames - Get fields for a note type
modelStyling - Get CSS styling for a note type

Prerequisites

Anki with AnkiConnect plugin installed
Node.js 20.19.0+

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)

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.

Option 2: NPM Package with STDIO (For Other MCP Clients)

Want to use Anki with MCP clients like Cursor IDE, Cline, or Zed Editor? Use the npm package with the --stdio flag:

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"
      }
    }
  }
}

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.

Option 3: HTTP Mode (For Remote AI Assistants)

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):

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)

# 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:

✅ One command instead of two terminals
✅ Automatic cleanup when you press Ctrl+C
✅ URL displayed directly in the startup banner
✅ Works with custom ports: ankimcp --port 8080 --ngrok

Security note: Anyone with your ngrok URL can access your Anki, so keep that URL private!

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.

Environment Variables (Optional)

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`

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

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

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

Note Updates Fail When Viewed in Browser

Workaround: Always close the browser or navigate to a different note before updating.

For more details and other known issues, see the full documentation.

Troubleshooting

ERR_REQUIRE_ESM Error

If you see an error like:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

This means your Node.js version is too old. The server requires Node.js 20.19.0 or later.

Check your version:

node --version

Solution: Update Node.js to version 20.19.0 or later. You can download it from nodejs.org or use a version manager like nvm.

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  # 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.

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

# 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

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

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              # 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

NPM Package Testing (Local)

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
Installing from .tgz simulates what users get from npm install -g ankimcp
This lets you test the full user experience before publishing to npm

Testing Commands

npm 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)

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.)

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

Useful Links

License & Attribution

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.