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 assistan
Add this skill
npx mdskills install anki-mcp/anki-mcp-desktopComprehensive MCP server with extensive tool coverage, clear setup instructions, and multiple deployment modes
1# Anki MCP Server23> **⚠️ IMPORTANT: Project Renamed (v0.8.2+)**4>5> This project has been renamed and moved:6> - **Package**: `anki-mcp-http` → `@ankimcp/anki-mcp-server`7> - **Commands**: `anki-mcp-http` → `ankimcp` or `anki-mcp-server`8> - **Repository**: `anki-mcp/anki-mcp-desktop` → `ankimcp/anki-mcp-server`9>10> The old `anki-mcp-http` package continues to be published for backward compatibility but is deprecated. Please migrate to the new package.11>12> **[Read more about this change →](https://ankimcp.ai/blog/organization-and-naming-update/)**1314[](https://github.com/ankimcp/anki-mcp-server/actions/workflows/test.yml)15[](https://www.npmjs.com/package/@ankimcp/anki-mcp-server)1617<div align="center">18 <img src="./docs/images/ankimcp.png" alt="Anki + MCP Integration" width="600" />1920 <p><strong>Seamlessly integrate <a href="https://apps.ankiweb.net">Anki</a> with AI assistants through the <a href="https://modelcontextprotocol.io">Model Context Protocol</a></strong></p>21</div>2223**Beta** - This project is in active development. APIs and features may change.2425A Model Context Protocol (MCP) server that enables AI assistants to interact with Anki, the spaced repetition flashcard application.2627Transform 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!2829## Examples and Tutorials3031For comprehensive guides, real-world examples, and step-by-step tutorials on using this MCP server with Claude Desktop, visit:3233**[ankimcp.ai](https://ankimcp.ai)** - Complete documentation with practical examples and use cases3435## Available Tools3637### Review & Study38- `sync` - Sync with AnkiWeb39- `get_due_cards` - Get cards for review40- `present_card` - Show card for review41- `rate_card` - Rate card performance4243### Deck Management44- `deckActions` - Unified deck operations:45 - `listDecks` - List all decks with optional statistics46 - `createDeck` - Create new decks (max 2 levels: "Parent::Child")47 - `deckStats` - Get comprehensive deck statistics48 - `changeDeck` - Move cards to a different deck4950### Note Management51- `addNote` - Create a single note52- `addNotes` - Create multiple notes in batch (up to 100, partial success supported)53- `findNotes` - Search for notes using Anki query syntax54- `notesInfo` - Get detailed information about notes (fields, tags, CSS)55- `updateNoteFields` - Update existing note fields (CSS-aware, supports HTML)56- `deleteNotes` - Delete notes and their cards5758### Media Management59- `mediaActions` - Manage media files (audio/images)60 - `storeMediaFile` - Upload media from base64 data, file paths, or URLs61 - `retrieveMediaFile` - Download media as base6462 - `getMediaFilesNames` - List media files with optional pattern filtering63 - `deleteMediaFile` - Remove media files6465**💡 Best Practice for Images:**66- ✅ **Use file paths** (e.g., `/Users/you/image.png`) - Fast and efficient67- ✅ **Use URLs** (e.g., `https://example.com/image.jpg`) - Direct download68- ❌ **Avoid base64** - Extremely slow and token-inefficient6970Just tell Claude where the image is, and it will handle the upload automatically using the most efficient method.7172### Model/Template Management73- `modelNames` - List note types74- `modelFieldNames` - Get fields for a note type75- `modelStyling` - Get CSS styling for a note type7677## Prerequisites7879- [Anki](https://apps.ankiweb.net/) with [AnkiConnect](https://github.com/FooSoft/anki-connect) plugin installed80- Node.js 20.19.0+8182## Installation8384This server works in two modes:8586- **Local mode (STDIO)** - For Claude Desktop on your computer (recommended for most users)87- **Remote mode (HTTP)** - For web-based AI assistants like ChatGPT or Claude.ai8889### Option 1: MCPB Bundle (Recommended - Local Mode)9091The easiest way to install this MCP server for Claude Desktop:92931. Download the latest `.mcpb` bundle from the [Releases](https://github.com/ankimcp/anki-mcp-server/releases) page942. In Claude Desktop, install the extension:95 - **Method 1**: Go to Settings → Extensions, then drag and drop the `.mcpb` file96 - **Method 2**: Go to Settings → Developer → Extensions → Install Extension, then select the `.mcpb` file973. Configure AnkiConnect URL if needed (defaults to `http://localhost:8765`)984. Restart Claude Desktop99100That's it! The bundle includes everything needed to run the server locally.101102### Option 2: NPM Package with STDIO (For Other MCP Clients)103104Want to use Anki with MCP clients like **Cursor IDE**, **Cline**, or **Zed Editor**? Use the npm package with the `--stdio` flag:105106**Supported Clients:**107- [Cursor IDE](https://www.cursor.com/) - AI-powered code editor108- [Cline](https://github.com/cline/cline) - VS Code extension for AI assistance109- [Zed Editor](https://zed.dev/) - Fast, modern code editor110- Other MCP clients that support STDIO transport111112**Configuration - Choose one method:**113114**Method 1: Using npx (recommended - no installation needed)**115116```json117{118 "mcpServers": {119 "anki-mcp": {120 "command": "npx",121 "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],122 "env": {123 "ANKI_CONNECT_URL": "http://localhost:8765"124 }125 }126 }127}128```129130**Method 2: Using global installation**131132First, install globally:133```bash134npm install -g @ankimcp/anki-mcp-server135```136137Then configure:138```json139{140 "mcpServers": {141 "anki-mcp": {142 "command": "ankimcp",143 "args": ["--stdio"],144 "env": {145 "ANKI_CONNECT_URL": "http://localhost:8765"146 }147 }148 }149}150```151152**Configuration file locations:**153- **Cursor IDE**: `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows)154- **Cline**: Accessible via settings UI in VS Code155- **Zed Editor**: Install as MCP extension through extension marketplace156157For client-specific features and troubleshooting, consult your MCP client's documentation.158159### Option 3: HTTP Mode (For Remote AI Assistants)160161Want to use Anki with ChatGPT or Claude.ai in your browser? This mode lets you connect web-based AI tools to your local Anki.162163**How it works (simple explanation):**1641. You run a small server on your computer (where Anki is installed)1652. Use the built-in `--ngrok` flag to automatically create a public tunnel URL1663. Share that URL with ChatGPT or Claude.ai1674. Now the AI can talk to your Anki through the internet!168169**New in v0.8.0:** Integrated ngrok support with the `--ngrok` flag - no need to run ngrok separately!170171**Setup - Choose one method:**172173**Method 1: Using npx (recommended - no installation needed)**174175```bash176# Quick start177npx @ankimcp/anki-mcp-server178179# With ngrok tunnel (recommended for web-based AI)180npx @ankimcp/anki-mcp-server --ngrok181182# With custom options183npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0184npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765185```186187**Method 2: Using global installation**188189```bash190# Install once191npm install -g @ankimcp/anki-mcp-server192193# Run the server194ankimcp195196# With ngrok tunnel (recommended for web-based AI)197ankimcp --ngrok198199# With custom options200ankimcp --port 8080 --host 0.0.0.0201ankimcp --anki-connect http://localhost:8765202```203204**Method 3: Install from source (for development)**205206```bash207npm install208npm run build209npm run start:prod:http210```211212**CLI Options:**213214```bash215ankimcp [options]216217Options:218 --stdio Run in STDIO mode (for MCP clients)219 -p, --port <port> Port to listen on (HTTP mode, default: 3000)220 -h, --host <host> Host to bind to (HTTP mode, default: 127.0.0.1)221 -a, --anki-connect <url> AnkiConnect URL (default: http://localhost:8765)222 --ngrok Start ngrok tunnel (requires global ngrok installation)223 --read-only Run in read-only mode (blocks all write operations)224 --help Show help message225226Usage with npx (no installation needed):227 npx @ankimcp/anki-mcp-server # HTTP mode228 npx @ankimcp/anki-mcp-server --port 8080 # Custom port229 npx @ankimcp/anki-mcp-server --stdio # STDIO mode230 npx @ankimcp/anki-mcp-server --ngrok # HTTP mode with ngrok tunnel231 npx @ankimcp/anki-mcp-server --read-only # Read-only mode232233Usage with global installation:234 npm install -g @ankimcp/anki-mcp-server # Install once235 ankimcp # HTTP mode236 ankimcp --port 8080 # Custom port237 ankimcp --stdio # STDIO mode238 ankimcp --ngrok # HTTP mode with ngrok tunnel239 ankimcp --read-only # Read-only mode240```241242**Read-Only Mode:**243244The `--read-only` flag prevents any modifications to your Anki collection. When enabled:245- All read operations work normally (browsing decks, viewing cards, searching notes)246- Review operations are allowed (sync, answerCards, suspend/unsuspend)247- Content modifications are blocked (addNote, deleteNotes, createDeck, updateNoteFields, etc.)248- Useful for safely exploring Anki data without risk of accidental changes249250```bash251# HTTP mode with read-only252ankimcp --read-only253254# STDIO mode with read-only255ankimcp --stdio --read-only256257# Can combine with other flags258ankimcp --ngrok --read-only259```260261You can also enable read-only mode via environment variable:262```bash263READ_ONLY=true ankimcp264```265266Or in MCP client configuration:267```json268{269 "mcpServers": {270 "anki-mcp": {271 "command": "npx",272 "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],273 "env": {274 "ANKI_CONNECT_URL": "http://localhost:8765"275 }276 }277 }278}279```280281**Using with ngrok:**282283**Method 1: Integrated (Recommended - One Command)**284285```bash286# One-time setup (if you haven't already):287npm install -g ngrok288ngrok config add-authtoken <your-token> # Get token from https://dashboard.ngrok.com289290# Start server with ngrok tunnel in one command:291ankimcp --ngrok292293# The tunnel URL will be displayed in the startup banner294# Example output:295# 🌐 Ngrok tunnel: https://abc123.ngrok-free.app296```297298**Method 2: Manual (Two Terminals)**299300```bash301# Terminal 1: Start the server302ankimcp303304# Terminal 2: Create tunnel305ngrok http 3000306307# Copy the ngrok URL (looks like: https://abc123.ngrok-free.app)308# Share this URL with your AI assistant309```310311**Benefits of `--ngrok` flag:**312- ✅ One command instead of two terminals313- ✅ Automatic cleanup when you press Ctrl+C314- ✅ URL displayed directly in the startup banner315- ✅ Works with custom ports: `ankimcp --port 8080 --ngrok`316317**Security note:** Anyone with your ngrok URL can access your Anki, so keep that URL private!318319### Option 4: Manual Installation from Source (Local Mode)320321For development or advanced usage:322323```bash324npm install325npm run build326```327328## Connect to Claude Desktop (Local Mode)329330You can configure the server in Claude Desktop by either:331- Going to: Settings → Developer → Edit Config332- Or manually editing the config file333334### Configuration335336Add the following to your Claude Desktop config:337338```json339{340 "mcpServers": {341 "anki-mcp": {342 "command": "node",343 "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],344 "env": {345 "ANKI_CONNECT_URL": "http://localhost:8765"346 }347 }348 }349}350```351352Replace `/path/to/anki-mcp-server` with your actual project path.353354### Config File Locations355356- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`357- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`358- **Linux**: `~/.config/Claude/claude_desktop_config.json`359360For more details, see the [official MCP documentation](https://modelcontextprotocol.io/docs/develop/connect-local-servers).361362## Environment Variables (Optional)363364| Variable | Description | Default |365|----------|-------------|---------|366| `ANKI_CONNECT_URL` | AnkiConnect URL | `http://localhost:8765` |367| `ANKI_CONNECT_API_VERSION` | API version | `6` |368| `ANKI_CONNECT_API_KEY` | API key if configured in AnkiConnect | - |369| `ANKI_CONNECT_TIMEOUT` | Request timeout in ms | `5000` |370| `READ_ONLY` | Enable read-only mode (`true` or `1`) | `false` |371372## Usage Examples373374### Searching and Updating Notes375376```377# Search for notes in a specific deck378findNotes(query: "deck:Spanish")379380# Get detailed information about notes381notesInfo(notes: [1234567890, 1234567891])382383# Update a note's fields (HTML content supported)384updateNoteFields(note: {385 id: 1234567890,386 fields: {387 "Front": "<b>¿Cómo estás?</b>",388 "Back": "How are you?"389 }390})391392# Delete notes (requires confirmation)393deleteNotes(notes: [1234567890], confirmDeletion: true)394```395396### Anki Query Syntax Examples397398The `findNotes` tool supports Anki's powerful query syntax:399400- `"deck:DeckName"` - All notes in a specific deck401- `"tag:important"` - Notes with the "important" tag402- `"is:due"` - Cards that are due for review403- `"is:new"` - New cards that haven't been studied404- `"added:7"` - Notes added in the last 7 days405- `"front:hello"` - Notes with "hello" in the front field406- `"flag:1"` - Notes with red flag407- `"prop:due<=2"` - Cards due within 2 days408- `"deck:Spanish tag:verb"` - Spanish deck notes with verb tag (AND)409- `"deck:Spanish OR deck:French"` - Notes from either deck410411### Important Notes412413#### CSS and HTML Handling414- The `notesInfo` tool returns CSS styling information for proper rendering awareness415- The `updateNoteFields` tool supports HTML content in fields and preserves CSS styling416- Each note model has its own CSS styling - use `modelStyling` to get model-specific CSS417418#### Update Warning419⚠️ **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](#known-issues) for more details.420421#### Deletion Safety422The `deleteNotes` tool requires explicit confirmation (`confirmDeletion: true`) to prevent accidental deletions. Deleting a note removes ALL associated cards permanently.423424## Known Issues425426For a comprehensive list of known issues and limitations, please visit our documentation:427428**[Known Issues Documentation](https://ankimcp.ai/docs/known-issues/)**429430### Critical Limitations431432#### Note Updates Fail When Viewed in Browser433⚠️ **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.434435**Workaround**: Always close the browser or navigate to a different note before updating.436437For more details and other known issues, see the [full documentation](https://ankimcp.ai/docs/known-issues/).438439## Troubleshooting440441### ERR_REQUIRE_ESM Error442443If you see an error like:444```445Error [ERR_REQUIRE_ESM]: require() of ES Module not supported446```447448This means your Node.js version is not supported. The server requires **Node.js 20.19.0+ or 22.12.0+**.449450> **Note:** Node.js 21.x is not supported. The `require(esm)` feature was added in Node 22 and backported to Node 20.17+, but was never available in Node 21. See [#16](https://github.com/ankimcp/anki-mcp-server/issues/16) for details.451452**Check your version:**453```bash454node --version455```456457**Solution:** Update Node.js to version 20.19.0+ or 22.12.0+. You can download it from [nodejs.org](https://nodejs.org/) or use a version manager like [nvm](https://github.com/nvm-sh/nvm).458459## Development460461### Transport Modes462463This server supports two MCP transport modes via **separate entry points**:464465#### STDIO Mode (Default)466- For local MCP clients like Claude Desktop467- Uses standard input/output for communication468- **Entry point**: `dist/main-stdio.js`469- **Run**: `npm run start:prod:stdio` or `node dist/main-stdio.js`470- **MCPB bundle**: Uses STDIO mode471472#### HTTP Mode (Streamable HTTP)473- For remote MCP clients and web-based integrations474- Uses MCP Streamable HTTP protocol475- **Entry point**: `dist/main-http.js`476- **Run**: `npm run start:prod:http` or `node dist/main-http.js`477- **Default port**: 3000 (configurable via `PORT` env var)478- **Default host**: `127.0.0.1` (configurable via `HOST` env var)479- **MCP endpoint**: `http://127.0.0.1:3000/` (root path)480481#### Building482483```bash484npm run build # Builds once, creates dist/ with both entry points485```486487Both `main-stdio.js` and `main-http.js` are in the same `dist/` directory. Choose which to run based on your needs.488489#### HTTP Mode Configuration490491**Environment Variables:**492- `PORT` - HTTP server port (default: 3000)493- `HOST` - Bind address (default: 127.0.0.1 for localhost-only)494- `ALLOWED_ORIGINS` - Comma-separated list of allowed origins for CORS (default: localhost)495- `LOG_LEVEL` - Logging level (default: info)496497**Security:**498- Origin header validation (prevents DNS rebinding attacks)499- Binds to localhost (127.0.0.1) by default500- No authentication in current version (OAuth support planned)501502**Example: Running Modes**503```bash504# Development - STDIO mode (watch mode with auto-rebuild)505npm run start:dev:stdio506507# Development - HTTP mode (watch mode with auto-rebuild)508npm run start:dev:http509510# Production - STDIO mode511npm run start:prod:stdio512# or513node dist/main-stdio.js514515# Production - HTTP mode516npm run start:prod:http517# or518PORT=8080 HOST=0.0.0.0 node dist/main-http.js519```520521### Building an MCPB Bundle522523To create a distributable MCPB bundle:524525```bash526npm run mcpb:bundle527```528529This command will:5301. Sync version from `package.json` to `manifest.json`5312. Remove old `.mcpb` files5323. Build the TypeScript project5334. Package `dist/` and `node_modules/` into an `.mcpb` file5345. Run `mcpb clean` to remove devDependencies (optimizes bundle from ~47MB to ~10MB)535536The output file will be named `anki-mcp-server-X.X.X.mcpb` and can be distributed for one-click installation.537538#### What Gets Bundled539540The MCPB package includes:541- Compiled JavaScript (`dist/` directory - includes both entry points)542- Production dependencies only (`node_modules/` - devDependencies removed by `mcpb clean`)543- Package metadata (`package.json`)544- Manifest configuration (`manifest.json` - configured to use `main-stdio.js`)545- Icon (`icon.png`)546547Source files, tests, and development configs are automatically excluded via `.mcpbignore`.548549### Logging in Claude Desktop550551When running as an MCPB extension in Claude Desktop, logs are written to:552553**Log Location**: `~/Library/Logs/Claude/` (macOS)554555The logs are split across multiple files:556- **main.log** - General Claude Desktop application logs557- **mcp-server-Anki MCP Server.log** - MCP protocol messages for this extension558- **mcp.log** - Combined MCP logs from all servers559560**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:561- Application startup and MCP protocol communication → MCP-specific log562- Server internal logging (pino) → Both MCP-specific log and sometimes main.log563564To view logs in real-time:565```bash566tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log567```568569### Debugging the MCP Server570571You can debug the MCP server using the MCP Inspector and attaching a debugger from your IDE (WebStorm, VS Code, etc.).572573**Note for HTTP Mode:** When testing HTTP mode (Streamable HTTP) with MCP Inspector, use "Connection Type: Via Proxy" to avoid CORS errors.574575#### Step 1: Configure Debug Server in MCP Inspector576577The `mcp-inspector-config.json` already includes a debug server configuration:578579```json580{581 "mcpServers": {582 "stdio-server-debug": {583 "type": "stdio",584 "command": "node",585 "args": ["--inspect-brk=9229", "dist/main-stdio.js"],586 "env": {587 "MCP_SERVER_NAME": "anki-mcp-stdio-debug",588 "MCP_SERVER_VERSION": "1.0.0",589 "LOG_LEVEL": "debug"590 },591 "note": "Anki MCP server with debugging enabled on port 9229"592 }593 }594}595```596597#### Step 2: Start the Debug Server598599Run the MCP Inspector with the debug server:600601```bash602npm run inspector:debug603```604605This will start the server with Node.js debugging enabled on port 9229 and pause execution at the first line.606607#### Step 3: Attach Debugger from Your IDE608609##### WebStorm6101. Go to **Run → Edit Configurations**6112. Add a new **Attach to Node.js/Chrome** configuration6123. Set the port to `9229`6134. Click **Debug** to attach614615##### VS Code6161. Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)6172. Select **Debug MCP Server (Attach)** configuration6183. Press F5 to attach619620#### Step 4: Set Breakpoints and Debug621622Once attached, you can:623- Set breakpoints in your TypeScript source files624- Step through code execution625- Inspect variables and call stack626- Use the debug console for evaluating expressions627628The debugger will work with source maps, allowing you to debug the original TypeScript code rather than the compiled JavaScript.629630### Debugging with Claude Desktop631632You can also debug the MCP server while it runs inside Claude Desktop by enabling the Node.js debugger and attaching your IDE.633634#### Step 1: Configure Claude Desktop for Debugging635636Update your Claude Desktop config to enable debugging:637638**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`639**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`640**Linux**: `~/.config/Claude/claude_desktop_config.json`641642```json643{644 "mcpServers": {645 "anki-mcp": {646 "command": "node",647 "args": [648 "--inspect=9229",649 "<path_to_project>/anki-mcp-server/dist/main-stdio.js"650 ],651 "env": {652 "ANKI_CONNECT_URL": "http://localhost:8765"653 }654 }655 }656}657```658659**Key change**: Add `--inspect=9229` before the path to `dist/main-stdio.js`660661**Debug options**:662- `--inspect=9229` - Start debugger immediately, doesn't block (recommended)663- `--inspect-brk=9229` - Pause execution until debugger attaches (for debugging startup issues)664665#### Step 2: Restart Claude Desktop666667After saving the config, restart Claude Desktop. The MCP server will now run with debugging enabled on port 9229.668669#### Step 3: Attach Debugger from Your IDE670671##### WebStorm6726731. Go to **Run → Edit Configurations**6742. Click the **+** button and select **Attach to Node.js/Chrome**6753. Configure:676 - **Name**: `Attach to Anki MCP (Claude Desktop)`677 - **Host**: `localhost`678 - **Port**: `9229`679 - **Attach to**: `Node.js < 8` or `Chrome or Node.js > 6.3` (depending on WebStorm version)6804. Click **OK**6815. Click **Debug** (Shift+F9) to attach682683##### VS Code6846851. Add to `.vscode/launch.json`:686687```json688{689 "version": "0.2.0",690 "configurations": [691 {692 "type": "node",693 "request": "attach",694 "name": "Attach to Anki MCP (Claude Desktop)",695 "port": 9229,696 "skipFiles": ["<node_internals>/**"],697 "sourceMaps": true,698 "outFiles": ["${workspaceFolder}/dist/**/*.js"]699 }700 ]701}702```7037042. Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)7053. Select **Attach to Anki MCP (Claude Desktop)**7064. Press F5 to attach707708#### Step 4: Debug in Real-Time709710Once attached, you can:711- Set breakpoints in your TypeScript source files (e.g., `src/mcp/primitives/essential/tools/create-model.tool.ts`)712- Use Claude Desktop normally - breakpoints will hit when tools are invoked713- Step through code execution714- Inspect variables and call stack715- Use the debug console716717**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!718719**Note**: The debugger stays attached as long as Claude Desktop is running. You can detach/reattach anytime without restarting Claude Desktop.720721### Build Commands722723```bash724npm run build # Build the project (compile TypeScript to JavaScript)725npm run start:dev:stdio # STDIO mode with watch (auto-rebuild)726npm run start:dev:http # HTTP mode with watch (auto-rebuild)727npm run type-check # Run TypeScript type checking728npm run lint # Run ESLint729npm run mcpb:bundle # Sync version, clean, build, and create MCPB bundle730```731732### NPM Package Testing (Local)733734Test the npm package locally before publishing:735736```bash737# 1. Create local package738npm run pack:local # Builds and creates @ankimcp/anki-mcp-server-*.tgz739740# 2. Install globally from local package741npm run install:local # Installs from ./@ankimcp/anki-mcp-server-*.tgz742743# 3. Test the command744ankimcp # Runs HTTP server on port 3000745746# 4. Uninstall when done testing747npm run uninstall:local # Removes global installation748```749750**How it works:**751- `npm pack` creates a `.tgz` file identical to what npm publish would create752- Installing from `.tgz` simulates what users get from `npm install -g ankimcp`753- This lets you test the full user experience before publishing to npm754755### Testing Commands756757```bash758npm test # Run all tests759npm run test:unit # Run unit tests only760npm run test:tools # Run tool-specific tests761npm run test:workflows # Run workflow integration tests762npm run test:e2e # Run end-to-end tests763npm run test:cov # Run tests with coverage report764npm run test:watch # Run tests in watch mode765npm run test:debug # Run tests with debugger766npm run test:ci # Run tests for CI (silent, with coverage)767```768769### Test Coverage770771The project maintains 70% minimum coverage thresholds for:772- Branches773- Functions774- Lines775- Statements776777Coverage reports are generated in the `coverage/` directory.778779## Versioning780781This project follows [Semantic Versioning](https://semver.org/) with a pre-1.0 development approach:782783- **0.x.x** - Beta/Development versions (current phase)784 - **0.1.x** - Bug fixes and patches785 - **0.2.0+** - New features or minor improvements786 - **Breaking changes** are acceptable in 0.x versions787788- **1.0.0** - First stable release789 - Will be released when the API is stable and tested790 - Breaking changes will require major version bumps (2.0.0, etc.)791792**Current Status**: `0.14.0` - Active beta development. Recent features include batch note creation (`addNotes`), integrated ngrok tunneling (`--ngrok` flag), media file management, model/template management, and comprehensive deck statistics. APIs may change based on feedback and testing.793794## Similar Projects795796If you're exploring Anki MCP integrations, here are other projects in this space:797798### [scorzeth/anki-mcp-server](https://github.com/scorzeth/anki-mcp-server)799- **Status**: Appears to be abandoned (no recent updates)800- Early implementation of Anki MCP integration801802### [nailuoGG/anki-mcp-server](https://github.com/nailuoGG/anki-mcp-server)803- **Approach**: Lightweight, single-file implementation804- **Architecture**: Procedural code structure with all tools in one file805- **Good for**: Simple use cases, minimal dependencies806807**Why this project differs:**808- **Enterprise-grade architecture**: Built on NestJS with dependency injection809- **Modular design**: Each tool is a separate class with clear separation of concerns810- **Maintainability**: Easy to extend with new features without touching existing code811- **Testing**: Comprehensive test suite with 70% coverage requirement812- **Type safety**: Strict TypeScript with Zod validation813- **Error handling**: Robust error handling with helpful user feedback814- **Production-ready**: Proper logging, progress reporting, and MCPB bundle support815- **Scalability**: Can easily grow from basic tools to complex workflows816817**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.818819## Useful Links820821- [Model Context Protocol Documentation](https://modelcontextprotocol.io/docs)822- [AnkiConnect API Documentation](https://git.sr.ht/~foosoft/anki-connect)823- [Claude Desktop Download](https://claude.ai/download)824- [Building Desktop Extensions (Anthropic Blog)](https://www.anthropic.com/engineering/desktop-extensions)825- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)826- [NestJS Documentation](https://docs.nestjs.com)827- [Anki Official Website](https://apps.ankiweb.net/)828829## License & Attribution830831This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).832833### Why AGPL-3.0?834835This license was chosen to maintain compatibility with Anki's AGPL-3.0 license for potential future integration scenarios.836837**What this means:**838- **Personal use**: Use the software freely839- **Running as a service for others**: You must provide source code access (AGPL Section 13)840- **Modifying and distributing**: Share your improvements under AGPL-3.0-or-later841842For complete license terms, see the [LICENSE](LICENSE) file.843844### Third-Party Attributions845846- **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](https://apps.ankiweb.net). For the official Anki application, visit [https://apps.ankiweb.net](https://apps.ankiweb.net).847848- **Model Context Protocol (MCP)** is an open standard by Anthropic. The MCP logo is from the official [MCP documentation repository](https://github.com/modelcontextprotocol/docs) and is used under the MIT License. For more information about MCP, visit [https://modelcontextprotocol.io](https://modelcontextprotocol.io).849850- 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.851
Full transparency — inspect the skill content before installing.