Skip to content
Back to search

anki-mcp-server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Anki, the spaced repetition flashcard application.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ankimcp--anki-mcp-server/badge.svg)](/listings/ankimcp--anki-mcp-server)

HTML

<a href="/listings/ankimcp--anki-mcp-server"><img src="/api/listings/ankimcp--anki-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

There are a few ways to get the server onto your machine. Once it's installed, head to [Connecting an AI Client](#connecting-an-ai-client) to wire it up to your AI assistant — locally or remotely.

npm (global or npx)

The general-purpose way to install the server, suitable for any MCP client that launches it directly.

Install it globally for clients that run the `ankimcp` command:

npm install -g @ankimcp/anki-mcp-server

Or run it on demand with no install required:

npx @ankimcp/anki-mcp-server

MCPB Bundle (Recommended for Claude Desktop)

The easiest way to install this MCP server for Claude Desktop:

1. Download the latest `.mcpb` bundle from the [Releases](https://github.com/ankimcp/anki-mcp-server/releases) page 2. 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 3. Configure AnkiConnect URL if needed (defaults to `http://localhost:8765`) 4. Restart Claude Desktop

That's it! The bundle includes everything needed to run the server locally.

> **For Anthropic MCP Directory reviewers:** a zero-to-integration walkthrough with a pre-populated sample deck lives in [`docs/reviewer-setup.md`](./docs/reviewer-setup.md).

Install from Source (for development)

For development or advanced usage (running the test suite requires Node.js 24.9+ — the npm test scripts load the ESM-only NestJS 12 packages via `require(esm)`, which Jest only supports there; the runtime requirement for *using* the server stays 22.12.0+):

npm install
npm run build

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,041 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Anki MCP Server
  2. [![Tests](https://github.com/ankimcp/anki-mcp-server/actions/workflows/test.yml/badge.svg)](https://github.com/ankimcp/anki-mcp-server/actions/workflows/test.yml)
  3. [![npm version](https://badge.fury.io/js/@ankimcp%2Fanki-mcp-server.svg)](https://www.npmjs.com/package/@ankimcp/anki-mcp-server)
  4. <div align="center">
  5. <img src="./docs/images/ankimcp.png" alt="Anki + MCP Integration" width="600" />
  6. <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>
  7. </div>
  8. > [!IMPORTANT]
  9. > **Prefer the [AnkiMCP addon](https://ankiweb.net/shared/info/124672614) for most setups.**
  10. >
  11. > The addon ([GitHub](https://github.com/ankimcp/anki-mcp-server-addon)) runs the MCP server directly inside Anki. There is no Node.js to install, no AnkiConnect to configure, no separate process to keep running: install it with code `124672614`, restart Anki, and the server is up every time Anki opens. It covers local HTTP access and remote access through a built-in tunnel.
  12. >
  13. > This repository is the right choice when you specifically need:
  14. >
  15. > - **STDIO transport** — Claude Desktop, Claude Code, Cursor, or any client that spawns the server as a subprocess
  16. > - **MCPB bundle** — the one-click `.mcpb` install for Claude Desktop
  17. >
  18. > For HTTP, tunnel, or web-based clients (claude.ai, ChatGPT), the addon is the simpler and better-supported path.
  19. >
  20. > This repo is **not** being deprecated. It stays maintained and released alongside the addon as part of the same [ankimcp.ai](https://ankimcp.ai) project.
  21. A Model Context Protocol (MCP) server that enables AI assistants to interact with Anki, the spaced repetition flashcard application.
  22. 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!
  23. ## Examples and Tutorials
  24. For comprehensive guides, real-world examples, and step-by-step tutorials on using this MCP server with Claude Desktop, visit:
  25. **[ankimcp.ai](https://ankimcp.ai)** - Complete documentation with practical examples and use cases
  26. See [`docs/`](./docs/README.md) for supplementary documentation, including the [reviewer setup guide](./docs/reviewer-setup.md) and the sample Anki deck.
  27. ## Example Use Cases
  28. Three representative prompts showing the tool flows this server enables:
  29. 1. **"Help me review my Spanish deck."** — The assistant offers to sync with AnkiWeb (`sync`), fetches due cards (`get_due_cards` with deck filter), presents each card (`present_card`), and records your rating (`rate_card`). Natural study conversation with explanations tailored to you.
  30. 2. **"Create 10 Arabic vocab cards with RTL styling."** — The assistant lists note types (`modelNames`), creates a custom RTL model if needed (`createModel` + `updateModelStyling` for right-to-left CSS), then batch-creates the cards (`addNotes`).
  31. 3. **"Import this image from my Downloads folder into the front of the selected note."** — The assistant uploads the local file (`storeMediaFile` with a file path), reads the currently-selected note from the browser (`guiSelectedNotes` + `notesInfo`), and updates the front field with an `<img>` tag (`updateNoteFields`).
  32. ## Available Tools
  33. The server exposes **53 MCP tools** — 42 essential tools for everyday Anki operations and 11 GUI tools that drive the Anki desktop interface for note editing/creation workflows.
  34. ### Essential Tools
  35. #### Review & Study
  36. - `sync` - Sync with AnkiWeb to pull latest data and push changes
  37. - `get_due_cards` - Get cards that are due for review, optionally filtered by deck (answers omitted unless `include_answer: true`, default `false`)
  38. - `get_cards` - Get cards with flexible filtering by state (due, new, learning, suspended, buried) and deck (answers omitted unless `include_answer: true`, default `false`)
  39. - `present_card` - Show a card for review with its question/front side
  40. - `rate_card` - Rate card performance (Again, Hard, Good, Easy) and schedule the next review
  41. - `forgetCards` - Reset cards to new, discarding their scheduling without recording a review
  42. - `setDueDate` - Reschedule cards to become due in N days (`"0"`, `"3-7"`, `"1!"`), without recording a review
  43. - `areSuspended` - Check suspension state for one or more cards without changing anything
  44. - `suspend` - Suspend cards so they are skipped during review until unsuspended
  45. - `unsuspend` - Unsuspend cards so they return to normal review
  46. > **Note:** `forgetCards` and `setDueDate` change scheduling *without* logging a review, which is what separates them from `rate_card`. Reach for them when a card's schedule is wrong rather than the answer: rating a card `Again` to bury it deeper records a real lapse and drops its ease factor, permanently skewing both future scheduling and your statistics. `forgetCards` wipes the interval and starts the card over; `setDueDate` keeps the card's history and just moves the next review.
  47. > **Note:** Card `front`/`back` content is rendered per card from its own template (as Anki shows it), so reversed and cloze cards display the correct direction. Static text added by your card templates appears in the output as well.
  48. #### Deck Management
  49. - `listDecks` - List all decks, optionally with per-deck study-queue statistics
  50. - `deckStats` - Get comprehensive statistics for a single deck (study queue, true card-state counts, ease/interval distributions)
  51. - `createDeck` - Create a new empty deck (supports `Parent::Child`, max 2 levels)
  52. - `changeDeck` - Move cards to a different deck (created if it doesn't exist)
  53. > **Note:** Deck statistics come in two flavours. The `counts` block (and everything `listDecks` reports) mirrors Anki's deck browser: cards **due today**, capped by each deck's **daily new/review limits**, with suspended and buried cards excluded — so `review` is not "mature cards" and the `other` bucket is just the arithmetic remainder (mostly review cards not due today plus new cards over the daily limit). For true per-state totals use the `states` block on `deckStats` / `collection_stats`, which counts `new`, `learning`, `review`, `suspended` and `buried` via Anki searches, ignoring due dates and daily limits.
  54. #### Note Management
  55. - `addNote` - Create a single note with specified fields and tags
  56. - `addNotes` - Batch-create up to 100 notes sharing a deck and model (partial success supported)
  57. - `findNotes` - Search for notes using Anki query syntax (`deck:`, `tag:`, `is:due`, etc.)
  58. - `notesInfo` - Get detailed information about notes (fields, tags, note type, card IDs; CSS comes from `modelStyling`)
  59. - `updateNoteFields` - Update existing note fields (CSS-aware, supports HTML content)
  60. - `deleteNotes` - Delete notes and all associated cards (destructive, requires confirmation)
  61. #### Tag Management
  62. - `getTags` - Get all tags in the collection (use first to avoid duplication)
  63. - `addTags` - Add space-separated tags to specified notes
  64. - `removeTags` - Remove space-separated tags from specified notes
  65. - `replaceTags` - Rename a tag across specified notes
  66. - `clearUnusedTags` - Remove orphaned tags not used by any notes (destructive)
  67. #### Media Management
  68. - `getMediaFilesNames` - List media files in `collection.media`, optionally filtered by pattern
  69. - `retrieveMediaFile` - Download a media file as base64 content
  70. - `storeMediaFile` - Upload media from base64 data, an absolute file path, or a URL
  71. - `deleteMediaFile` - Remove a media file from `collection.media` (destructive)
  72. **💡 Best Practice for Images:**
  73. - ✅ **Use file paths** (e.g., `/Users/you/image.png`) - Fast and efficient
  74. - ✅ **Use URLs** (e.g., `https://example.com/image.jpg`) - Direct download
  75. - ❌ **Avoid base64** - Extremely slow and token-inefficient
  76. Just tell Claude where the image is, and it will handle the upload automatically using the most efficient method.
  77. #### Model/Template Management
  78. - `modelNames` - List all available note types/models
  79. - `modelFieldNames` - Get field names for a specific note type
  80. - `modelStyling` - Get CSS styling information for a note type
  81. - `modelTemplates` - Get the card templates (Front and Back HTML) for a note type
  82. - `createModel` - Create a new note type with custom fields, card templates, and CSS (e.g., RTL models)
  83. - `updateModelStyling` - Update the CSS styling for an existing note type (applies to all its cards)
  84. - `updateModelTemplates` - Update the card templates (Front and Back HTML) for an existing note type (applies to all its cards)
  85. - `addModelField` - Add a new field to an existing note type (appended at the end or inserted at a specific position)
  86. - `removeModelField` - Remove a field from an existing note type (deletes its content from all notes; requires explicit confirmation)
  87. - `renameModelField` - Rename a field in an existing note type (Anki rewrites references to the old name in the card templates)
  88. - `repositionModelField` - Change the position of a field within an existing note type
  89. #### Statistics
  90. - `collection_stats` - Aggregated statistics across all decks with per-deck breakdown and collection-wide card-state counts
  91. - `review_stats` - Review history analysis (temporal patterns, retention metrics, study streaks)
  92. ### GUI Tools
  93. Tools that drive the Anki desktop interface. Intended for note editing/creation and deck-management workflows, **not** for review sessions.
  94. - `guiBrowse` - Open the Card Browser and search for cards
  95. - `guiSelectCard` - Select a specific card in the Card Browser
  96. - `guiSelectedNotes` - Get IDs of notes currently selected in the Card Browser
  97. - `guiAddCards` - Open the Add Cards dialog with preset note details
  98. - `guiEditNote` - Open the note editor for a specific note
  99. - `guiDeckOverview` - Open the Deck Overview dialog for a specific deck
  100. - `guiDeckBrowser` - Open the Deck Browser dialog
  101. - `guiCurrentCard` - Get info about the current card in review mode (includes the answer; errors outside review mode)
  102. - `guiShowQuestion` - Show the question side of the current card
  103. - `guiShowAnswer` - Show the answer side of the current card
  104. - `guiUndo` - Undo the last action in Anki
  105. ## Prerequisites
  106. - [Anki](https://apps.ankiweb.net/) with [AnkiConnect](https://github.com/FooSoft/anki-connect) plugin installed
  107. - Node.js 22.12.0+
  108. ## Installation
  109. There are a few ways to get the server onto your machine. Once it's installed, head to [Connecting an AI Client](#connecting-an-ai-client) to wire it up to your AI assistant — locally or remotely.
  110. ### npm (global or npx)
  111. The general-purpose way to install the server, suitable for any MCP client that launches it directly.
  112. Install it globally for clients that run the `ankimcp` command:
  113. ```bash
  114. npm install -g @ankimcp/anki-mcp-server
  115. ```
  116. Or run it on demand with no install required:
  117. ```bash
  118. npx @ankimcp/anki-mcp-server
  119. ```
  120. ### MCPB Bundle (Recommended for Claude Desktop)
  121. The easiest way to install this MCP server for Claude Desktop:
  122. 1. Download the latest `.mcpb` bundle from the [Releases](https://github.com/ankimcp/anki-mcp-server/releases) page
  123. 2. In Claude Desktop, install the extension:
  124. - **Method 1**: Go to Settings → Extensions, then drag and drop the `.mcpb` file
  125. - **Method 2**: Go to Settings → Developer → Extensions → Install Extension, then select the `.mcpb` file
  126. 3. Configure AnkiConnect URL if needed (defaults to `http://localhost:8765`)
  127. 4. Restart Claude Desktop
  128. That's it! The bundle includes everything needed to run the server locally.
  129. > **For Anthropic MCP Directory reviewers:** a zero-to-integration walkthrough with a pre-populated sample deck lives in [`docs/reviewer-setup.md`](./docs/reviewer-setup.md).
  130. ### Install from Source (for development)
  131. For development or advanced usage (running the test suite requires Node.js 24.9+ — the npm test scripts load the ESM-only NestJS 12 packages via `require(esm)`, which Jest only supports there; the runtime requirement for *using* the server stays 22.12.0+):
  132. ```bash
  133. npm install
  134. npm run build
  135. ```
  136. ## Connecting an AI Client
  137. There are two ways an AI assistant can reach this server, depending on where the assistant runs:
  138. - **[Local](#local)** — the server runs on the same machine as the AI client (Claude Desktop, Cursor, Cline, Zed, or a local browser session). Use **STDIO** for desktop MCP clients, **HTTP** for local web-based tools.
  139. - **[Remote](#remote)** — a hosted/remote AI (e.g. ChatGPT or Claude.ai in the cloud) needs to reach the Anki running on your local machine. Use the managed **Tunnel** (✅ recommended — authenticated) or, as a lighter-weight unauthenticated alternative, **ngrok**.
  140. ### Local
  141. The server runs on the same computer as your AI client and talks to AnkiConnect on `localhost`.
  142. #### STDIO (primary local integration)
  143. STDIO is the standard transport for local desktop MCP clients — **Claude Desktop**, **Cursor IDE**, **Cline**, **Zed Editor**, **opencode**, and others. The client launches the server as a subprocess and communicates over standard input/output.
  144. **Supported Clients:**
  145. - [Claude Desktop](https://claude.ai/download)
  146. - [Cursor IDE](https://www.cursor.com/) - AI-powered code editor
  147. - [Cline](https://github.com/cline/cline) - VS Code extension for AI assistance
  148. - [Zed Editor](https://zed.dev/) - Fast, modern code editor
  149. - [opencode](https://opencode.ai) - Terminal AI coding agent
  150. - Other MCP clients that support STDIO transport
  151. For Claude Desktop, the [MCPB bundle](#mcpb-bundle-recommended-for-claude-desktop) is the easiest path. For other clients, configure the npm package with the `--stdio` flag.
  152. **Configuration - Choose one method:**
  153. **Method 1: Using npx (recommended - no installation needed)**
  154. ```json
  155. {
  156. "mcpServers": {
  157. "anki-mcp": {
  158. "command": "npx",
  159. "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
  160. "env": {
  161. "ANKI_CONNECT_URL": "http://localhost:8765"
  162. }
  163. }
  164. }
  165. }
  166. ```
  167. **Method 2: Using global installation**
  168. First, install globally:
  169. ```bash
  170. npm install -g @ankimcp/anki-mcp-server
  171. ```
  172. Then configure:
  173. ```json
  174. {
  175. "mcpServers": {
  176. "anki-mcp": {
  177. "command": "ankimcp",
  178. "args": ["--stdio"],
  179. "env": {
  180. "ANKI_CONNECT_URL": "http://localhost:8765"
  181. }
  182. }
  183. }
  184. }
  185. ```
  186. **opencode** uses its own format — servers go under `mcp`, the command is a single array, and environment variables go under `environment`:
  187. ```json
  188. {
  189. "$schema": "https://opencode.ai/config.json",
  190. "mcp": {
  191. "anki-mcp": {
  192. "type": "local",
  193. "command": ["npx", "-y", "@ankimcp/anki-mcp-server", "--stdio"],
  194. "enabled": true,
  195. "environment": {
  196. "ANKI_CONNECT_URL": "http://localhost:8765"
  197. }
  198. }
  199. }
  200. }
  201. ```
  202. **Configuration file locations:**
  203. - **Cursor IDE**: `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows)
  204. - **Cline**: Accessible via settings UI in VS Code
  205. - **Zed Editor**: Install as MCP extension through extension marketplace
  206. - **opencode**: `opencode.json` in your project root, or `~/.config/opencode/opencode.json` globally
  207. For client-specific features and troubleshooting, consult your MCP client's documentation. See also [Connect to Claude Desktop](#connect-to-claude-desktop-local-mode) for a config that points directly at a built `dist/main-stdio.js`.
  208. #### HTTP (local web-based AI)
  209. HTTP mode runs the server as a local web server speaking the MCP Streamable HTTP protocol. It's the transport a web-based AI tool talks to when pointed at your machine, and it's also what the [Remote](#remote) options expose to the outside world. On its own, HTTP mode binds to `localhost` only.
  210. > **Binding beyond localhost?** If you pass `--host 0.0.0.0` (or run behind a reverse proxy/public domain), the server only accepts loopback `Host` headers by default for DNS-rebinding protection — set `ALLOWED_HOSTS` to the hostname(s) clients use. See [HTTP Mode Configuration](#http-mode-configuration).
  211. **Setup - Choose one method:**
  212. **Method 1: Using npx (recommended - no installation needed)**
  213. ```bash
  214. # Quick start
  215. npx @ankimcp/anki-mcp-server
  216. # With custom options
  217. npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
  218. npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765
  219. ```
  220. **Method 2: Using global installation**
  221. ```bash
  222. # Install once
  223. npm install -g @ankimcp/anki-mcp-server
  224. # Run the server
  225. ankimcp
  226. # With custom options
  227. ankimcp --port 8080 --host 0.0.0.0
  228. ankimcp --anki-connect http://localhost:8765
  229. ```
  230. **Method 3: Install from source (for development)**
  231. ```bash
  232. npm install
  233. npm run build
  234. npm run start:prod:http
  235. ```
  236. To make a local HTTP server reachable by a cloud-hosted AI, use one of the [Remote](#remote) options below.
  237. ### Remote
  238. A hosted/remote AI (such as ChatGPT or Claude.ai running in the cloud) can't reach `localhost` directly. These options expose your **local** Anki to the internet so a remote assistant can talk to it.
  239. #### Tunnel (✅ Recommended)
  240. > **Recommended remote path — authenticated & secure.** Unlike a raw public port, tunnel mode requires you to log in (OAuth 2.0 device flow), so the endpoint isn't open to anyone who guesses the URL.
  241. Tunnel mode lets web-based AI assistants reach your **local** Anki without running your own tunnel. The server connects out to the managed AnkiMCP tunnel service (`wss://tunnel.ankimcp.ai`) over a WebSocket and is assigned a public URL. Authentication is built in — no ngrok account or separate tunnel process required, and you log in once.
  242. **Log in (OAuth device flow):**
  243. Tunnel mode uses the OAuth 2.0 Device Authorization Grant. Logging in opens your browser automatically to an approval page with the code already embedded in the URL — nothing to type, just approve. (If the browser can't open, the terminal prints a verification URL and code to enter manually as a fallback.) On success, credentials are saved to `~/.ankimcp/credentials.json` (file permissions `0600`).
  244. ```bash
  245. # Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
  246. ankimcp --login
  247. npx @ankimcp/anki-mcp-server --login
  248. # Clear saved credentials
  249. ankimcp --logout
  250. ```
  251. **Start the tunnel:**
  252. ```bash
  253. # Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
  254. ankimcp --tunnel
  255. npx @ankimcp/anki-mcp-server --tunnel
  256. # Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
  257. ankimcp --tunnel wss://my-tunnel.example.com
  258. ```
  259. If no credentials exist, `--tunnel` automatically starts the login flow first, then continues to the tunnel. This auto-login requires an interactive terminal — when stdout is not a TTY (systemd, headless Docker, CI), the server fast-fails and asks you to run `ankimcp --login` first. Once connected, the public tunnel URL is printed; press Ctrl+C to disconnect. Share that URL with your AI assistant.
  260. **Tunnel-mode environment variables:**
  261. | Variable | Description | Default |
  262. |----------|-------------|---------|
  263. | `TUNNEL_SERVER_URL` | Tunnel server WebSocket URL (the `--tunnel`/`--login` flag value overrides this) | `wss://tunnel.ankimcp.ai` |
  264. | `TUNNEL_AUTH_CLIENT_ID` | OAuth client ID for the device flow. Advanced — only needed when pointing at a self-hosted tunnel/auth service. | (built-in) |
  265. The device-flow auth endpoints (`/auth/device`, `/auth/token`) are derived from `TUNNEL_SERVER_URL`, so pointing `--tunnel` (or `TUNNEL_SERVER_URL`) at a different host also moves authentication to that host.
  266. **How it works:** Tunnel mode runs the MCP server in-process behind an in-memory transport (`TunnelTransport`). That transport owns the MCP server and turns each relayed request body into a response, and `TunnelClient` bridges it to the remote tunnel service over a WebSocket — relaying MCP requests in and responses out. AnkiConnect is still only ever reached on your local machine.
  267. **Protocol revisions:** Because the tunnel connects the MCP server in-process, tunnel mode serves the 2025 revision of the MCP protocol only, while STDIO and HTTP modes serve both 2025 and the newer 2026-07-28 revision. Every tool behaves the same either way — but a client that speaks only 2026-07-28 is turned away over the tunnel with a protocol-version error; run [STDIO](#stdio-primary-local-integration) or [HTTP](#http-local-web-based-ai) mode for that client.
  268. #### ngrok (unauthenticated alternative)
  269. If you'd rather expose [local HTTP mode](#http-local-web-based-ai) publicly without an account on the managed tunnel, the built-in `--ngrok` flag launches an [ngrok](https://ngrok.com/) subprocess (`src/services/ngrok.service.ts`) and prints the public URL in the startup banner:
  270. ```bash
  271. # One-time ngrok setup, then:
  272. ankimcp --ngrok
  273. ```
  274. This route is **unauthenticated** — anyone with the URL can reach your Anki, so it's less secure than [Tunnel](#tunnel--recommended). Prefer Tunnel unless you have a specific reason to manage your own ngrok endpoint. (Requires a global ngrok install and authtoken.)
  275. The `--ngrok` flag launches ngrok with `--host-header=rewrite`, so ngrok rewrites the upstream `Host` to `localhost` before forwarding. That keeps requests within the loopback Host allowlist (see [DNS-rebinding protection](#http-mode-configuration)) without you having to add the public `*.ngrok` domain to `ALLOWED_HOSTS`. If you instead run ngrok manually, use the same flag — `ngrok http --host-header=rewrite 3000` — otherwise ngrok forwards the public ngrok hostname as `Host` and the server rejects it with `403`.
  276. ### CLI Options (all modes)
  277. ```bash
  278. ankimcp [options]
  279. Options:
  280. --stdio Run in STDIO mode (for MCP clients)
  281. --tunnel [url] Connect via the managed tunnel (authenticated)
  282. --login Authenticate for tunnel mode (OAuth device flow)
  283. --logout Clear saved tunnel credentials
  284. -p, --port <number> Port to listen on (HTTP mode; default: 3000, or PORT env var)
  285. -h, --host <address> Host to bind to (HTTP mode; default: 127.0.0.1, or HOST env var)
  286. -a, --anki-connect <url> AnkiConnect URL (default: http://localhost:8765, or ANKI_CONNECT_URL env var)
  287. --ngrok Start ngrok tunnel (requires global ngrok installation)
  288. --read-only Run in read-only mode (blocks content changes and rescheduling; rating, suspend and sync still work)
  289. --help Show help message
  290. Usage with npx (no installation needed):
  291. npx @ankimcp/anki-mcp-server # HTTP mode
  292. npx @ankimcp/anki-mcp-server --port 8080 # Custom port
  293. npx @ankimcp/anki-mcp-server --stdio # STDIO mode
  294. npx @ankimcp/anki-mcp-server --tunnel # Managed tunnel mode
  295. npx @ankimcp/anki-mcp-server --ngrok # HTTP mode with ngrok tunnel
  296. npx @ankimcp/anki-mcp-server --read-only # Read-only mode
  297. Usage with global installation:
  298. npm install -g @ankimcp/anki-mcp-server # Install once
  299. ankimcp # HTTP mode
  300. ankimcp --port 8080 # Custom port
  301. ankimcp --stdio # STDIO mode
  302. ankimcp --tunnel # Managed tunnel mode
  303. ankimcp --ngrok # HTTP mode with ngrok tunnel
  304. ankimcp --read-only # Read-only mode
  305. ```
  306. ### Read-Only Mode (all modes)
  307. The `--read-only` flag (or `READ_ONLY=true`) blocks changes to note content, decks, tags, media and note types, and manual rescheduling of cards. When enabled:
  308. - All read operations work normally (browsing decks, viewing cards, searching notes)
  309. - These changes are still allowed: rating a card during review (`rate_card`), suspending/unsuspending cards (`suspend`, `unsuspend`), syncing with AnkiWeb (`sync`), and the GUI tools that navigate Anki's windows (`guiBrowse`, `guiDeckOverview`, …)
  310. - Content modifications are blocked (addNote, deleteNotes, createDeck, updateNoteFields, etc.); `createDeck` for a deck that already exists still succeeds, since nothing is written
  311. - Manual rescheduling is blocked: `forgetCards` (reset to new) and `setDueDate`
  312. - `guiUndo` is blocked, since an undo can revert a change to the collection
  313. - `guiAddCards` and `guiEditNote` are blocked, since a note added or saved in the dialog they open is written to the collection
  314. - Useful for exploring Anki data without accidental changes to its content
  315. ```bash
  316. # HTTP mode with read-only
  317. ankimcp --read-only
  318. # STDIO mode with read-only
  319. ankimcp --stdio --read-only
  320. # Can combine with other flags
  321. ankimcp --ngrok --read-only
  322. ```
  323. You can also enable read-only mode via environment variable:
  324. ```bash
  325. READ_ONLY=true ankimcp
  326. ```
  327. Or in MCP client configuration:
  328. ```json
  329. {
  330. "mcpServers": {
  331. "anki-mcp": {
  332. "command": "npx",
  333. "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],
  334. "env": {
  335. "ANKI_CONNECT_URL": "http://localhost:8765"
  336. }
  337. }
  338. }
  339. }
  340. ```
  341. ## Connect to Claude Desktop (Local Mode)
  342. You can configure the server in Claude Desktop by either:
  343. - Going to: Settings → Developer → Edit Config
  344. - Or manually editing the config file
  345. ### Configuration
  346. Add the following to your Claude Desktop config:
  347. ```json
  348. {
  349. "mcpServers": {
  350. "anki-mcp": {
  351. "command": "node",
  352. "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
  353. "env": {
  354. "ANKI_CONNECT_URL": "http://localhost:8765"
  355. }
  356. }
  357. }
  358. }
  359. ```
  360. Replace `/path/to/anki-mcp-server` with your actual project path.
  361. ### Config File Locations
  362. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  363. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  364. - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  365. For more details, see the [official MCP documentation](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
  366. ## Environment Variables (Optional)
  367. | Variable | Description | Default |
  368. |----------|-------------|---------|
  369. | `ANKI_CONNECT_URL` | AnkiConnect URL | `http://localhost:8765` |
  370. | `ANKI_CONNECT_API_VERSION` | API version | `6` |
  371. | `ANKI_CONNECT_API_KEY` | API key if configured in AnkiConnect | - |
  372. | `ANKI_CONNECT_TIMEOUT` | Request timeout in ms | `5000` |
  373. | `READ_ONLY` | Enable read-only mode (`true` or `1`) | `false` |
  374. | `PORT` | HTTP mode: port to listen on (`--port` flag takes precedence) | `3000` |
  375. | `HOST` | HTTP mode: address to bind to (`--host` flag takes precedence) | `127.0.0.1` |
  376. | `ALLOWED_HOSTS` | HTTP mode: extra `Host` header values to accept beyond loopback (comma-separated hostnames). Required when binding to a LAN/public address or running behind a reverse proxy. See [HTTP Mode Configuration](#http-mode-configuration). | loopback only |
  377. | `ALLOWED_ORIGINS` | HTTP mode: comma-separated allowlist of browser `Origin`/`Referer` patterns (wildcards supported, e.g. `https://*.ngrok.io`; `*` matches one host label or a port, so a multi-label host such as `https://a.b.ngrok.io` needs its own entry). | `http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*` |
  378. | `TUNNEL_SERVER_URL` | Tunnel server WebSocket URL (tunnel mode only) | `wss://tunnel.ankimcp.ai` |
  379. | `MEDIA_ALLOWED_TYPES` | Extra MIME types to allow for file path imports (comma-separated, e.g., `application/pdf`) | - |
  380. | `MEDIA_IMPORT_DIR` | Restrict file path imports to this directory | - |
  381. | `MEDIA_ALLOWED_HOSTS` | Allow specific private network hosts for URL imports (comma-separated, e.g., `192.168.1.50,my-nas`) | - |
  382. ## Usage Examples
  383. ### Searching and Updating Notes
  384. ```
  385. # Search for notes in a specific deck
  386. findNotes(query: "deck:Spanish")
  387. # Get detailed information about notes
  388. notesInfo(notes: [1234567890, 1234567891])
  389. # Update a note's fields (HTML content supported)
  390. updateNoteFields(note: {
  391. id: 1234567890,
  392. fields: {
  393. "Front": "<b>¿Cómo estás?</b>",
  394. "Back": "How are you?"
  395. }
  396. })
  397. # Delete notes (requires confirmation)
  398. deleteNotes(notes: [1234567890], confirmDeletion: true)
  399. ```
  400. ### Anki Query Syntax Examples
  401. The `findNotes` tool supports Anki's powerful query syntax:
  402. - `"deck:DeckName"` - All notes in a specific deck
  403. - `"tag:important"` - Notes with the "important" tag
  404. - `"is:due"` - Cards that are due for review
  405. - `"is:new"` - New cards that haven't been studied
  406. - `"added:7"` - Notes added in the last 7 days
  407. - `"front:hello"` - Notes with "hello" in the front field
  408. - `"flag:1"` - Notes with red flag
  409. - `"prop:due<=2"` - Cards due within 2 days
  410. - `"deck:Spanish tag:verb"` - Spanish deck notes with verb tag (AND)
  411. - `"deck:Spanish OR deck:French"` - Notes from either deck
  412. ### Important Notes
  413. #### CSS and HTML Handling
  414. - The `notesInfo` tool returns each note's note type name; the CSS itself comes from `modelStyling`
  415. - The `updateNoteFields` tool supports HTML content in fields and preserves CSS styling
  416. - Each note model has its own CSS styling - use `modelStyling` to get model-specific CSS
  417. #### Update Warning
  418. ⚠️ **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.
  419. #### Deletion Safety
  420. The `deleteNotes` tool requires explicit confirmation (`confirmDeletion: true`) to prevent accidental deletions. Deleting a note removes ALL associated cards permanently.
  421. ## Security
  422. ### Media File Path and URL Validation
  423. The media tools (`storeMediaFile`, `retrieveMediaFile`, `deleteMediaFile`) and `updateNoteFields` audio/picture fields include security validation to prevent misuse via prompt injection:
  424. - **File path imports** are restricted to media file types only (images, audio, video). Non-media files (e.g., SSH keys, credentials, shell configs) are rejected based on MIME type. Symlinks are resolved first, so the type and directory checks apply to the link's target, not its name. The path is resolved on the machine running the MCP server, so the file has to exist there — this matters when Anki runs in Docker or on another host. Configure `MEDIA_ALLOWED_TYPES` to allow additional file types, or `MEDIA_IMPORT_DIR` to restrict imports to a specific directory.
  425. - **URL imports** are validated against SSRF attacks. Requests to private networks (10.x, 172.16.x, 192.168.x), loopback (127.x), link-local (169.254.x), and non-HTTP(S) schemes are blocked. Configure `MEDIA_ALLOWED_HOSTS` to allow specific private network hosts.
  426. - **Filenames** must be plain names (e.g., `audio.mp3`). Names containing path separators, `.`/`..` as the whole name, or null bytes are rejected rather than rewritten, so distinct names never collapse onto the same file.
  427. These protections apply to `storeMediaFile`, `retrieveMediaFile`, `deleteMediaFile`, and `updateNoteFields` audio/picture fields.
  428. > Path traversal vulnerability reported by [Hideaki Takahashi](https://github.com/Koukyosyumei).
  429. ### DNS-Rebinding Protection (HTTP transport)
  430. When running in HTTP mode, the server validates the `Host` header on every request. By default only loopback hosts (`localhost`, `127.0.0.1`, `::1`) are accepted, regardless of port. `Host` is a browser-forbidden header, so a malicious web page cannot forge it — this closes the DNS-rebinding path where a rebound page reaches the local server with a spoofed `Host` and no `Origin`, and reaches the MCP tools. A disallowed `Host` is rejected with `403`.
  431. If you bind to `0.0.0.0`, run behind a reverse proxy, or expose a public tunnel domain, set `ALLOWED_HOSTS` (comma-separated hostnames) to permit those hosts. When tunneling with ngrok the server uses `--host-header=rewrite`, so the upstream still sees a loopback `Host`. See [HTTP Mode Configuration](#http-mode-configuration) for the full list of options.
  432. > DNS-rebinding vulnerability reported by [avishaigo-commits](https://github.com/avishaigo-commits) and [yotampe-pluto](https://github.com/yotampe-pluto).
  433. ## Privacy Policy
  434. This MCP server runs locally on your machine and collects no telemetry, analytics, or usage data.
  435. Full policy: **[https://ankimcp.ai/privacy/](https://ankimcp.ai/privacy/)**
  436. - **Data collection**: The server collects nothing. It proxies requests between your AI assistant and your local AnkiConnect plugin.
  437. - **Usage / storage**: No server-side storage. All flashcard data stays in your Anki installation on your own device.
  438. - **Third-party sharing**: None. The server only talks to the AnkiConnect URL you configure (default: localhost). If you enable Anki's built-in AnkiWeb sync, that happens between your Anki install and AnkiWeb directly — outside this server's scope.
  439. - **Retention**: Not applicable — no data is retained server-side.
  440. - **Contact**: support@ankimcp.ai
  441. ## Known Issues
  442. For a comprehensive list of known issues and limitations, please visit our documentation:
  443. **[Known Issues Documentation](https://ankimcp.ai/docs/known-issues/)**
  444. ### Critical Limitations
  445. #### Note Updates Fail When Viewed in Browser
  446. ⚠️ **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.
  447. **Workaround**: Always close the browser or navigate to a different note before updating.
  448. For more details and other known issues, see the [full documentation](https://ankimcp.ai/docs/known-issues/).
  449. ## Troubleshooting
  450. ### ERR_REQUIRE_ESM Error
  451. If you see an error like:
  452. ```
  453. Error [ERR_REQUIRE_ESM]: require() of ES Module not supported
  454. ```
  455. This means your Node.js version is not supported. The server requires **Node.js 22.12.0+**.
  456. > **Note:** The minimum supported runtime is Node.js 22.12.0. Node.js 20 (Iron) reached end-of-life on 2026-04-30 and is no longer supported.
  457. **Check your version:**
  458. ```bash
  459. node --version
  460. ```
  461. **Solution:** Update Node.js to version 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).
  462. ## Development
  463. ### Transport Modes
  464. This server supports three MCP transport modes via **separate entry points**:
  465. #### STDIO Mode (Default)
  466. - For local MCP clients like Claude Desktop
  467. - Uses standard input/output for communication
  468. - **Entry point**: `dist/main-stdio.js`
  469. - **Run**: `npm run start:prod:stdio` or `node dist/main-stdio.js`
  470. - **MCPB bundle**: Uses STDIO mode
  471. #### HTTP Mode (Streamable HTTP)
  472. - For remote MCP clients and web-based integrations
  473. - Uses MCP Streamable HTTP protocol
  474. - **Entry point**: `dist/main-http.js`
  475. - **Run**: `npm run start:prod:http` or `node dist/main-http.js`
  476. - **Default port**: 3000 (configurable via `PORT` env var)
  477. - **Default host**: `127.0.0.1` (configurable via `HOST` env var)
  478. - **MCP endpoint**: `http://127.0.0.1:3000/` (root path)
  479. #### Tunnel Mode (Managed WebSocket Tunnel)
  480. - For web-based AI assistants via the managed AnkiMCP tunnel service, with built-in authentication
  481. - The MCP server runs in-process behind an in-memory transport; `TunnelTransport` owns the MCP server and `TunnelClient` bridges it to the tunnel service over a WebSocket
  482. - **Protocol**: serves the 2025 MCP revision only (STDIO and HTTP also serve 2026-07-28)
  483. - **Entry point**: `dist/main-tunnel.js`
  484. - **Run**: `node dist/main-tunnel.js --tunnel` (or `ankimcp --tunnel`)
  485. - **Auth**: `ankimcp --login` / `ankimcp --logout`; credentials stored at `~/.ankimcp/credentials.json` (`0600`)
  486. - **Dev**: `npm run start:dev:tunnel` (watch mode, runs `--tunnel --debug`)
  487. #### Building
  488. ```bash
  489. npm run build # Builds once, creates dist/ with all three entry points
  490. ```
  491. `main-stdio.js`, `main-http.js`, and `main-tunnel.js` are all built into the same `dist/` directory. Choose which to run based on your needs.
  492. #### HTTP Mode Configuration
  493. **Environment Variables:**
  494. - `PORT` - HTTP server port (default: 3000)
  495. - `HOST` - Bind address (default: 127.0.0.1 for localhost-only)
  496. - `ALLOWED_HOSTS` - Comma-separated extra `Host` header values to accept beyond the built-in loopback set (`localhost`, `127.0.0.1`, `::1`). Hostname-only and port-agnostic. Default: loopback only.
  497. - `ALLOWED_ORIGINS` - Comma-separated allowlist of browser `Origin`/`Referer` patterns; wildcards supported (e.g. `https://*.ngrok.io`; `*` matches one host label or a port, so a multi-label host such as `https://a.b.ngrok.io` needs its own entry). Default: `http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*`.
  498. - `LOG_LEVEL` - Logging level (default: info)
  499. **Security:**
  500. - **Host header validation (DNS-rebinding protection)** — every HTTP request must carry a `Host` header that matches the allowlist. By default only loopback hosts (`localhost`, `127.0.0.1`, `::1`) are accepted, regardless of port. `Host` is a browser-forbidden header, so a malicious web page cannot forge it — this closes the [DNS-rebinding](https://github.com/ankimcp/anki-mcp-server/security/advisories) path where a rebound page reaches the server with a spoofed `Host` and no `Origin`. A disallowed `Host` is rejected with `403`.
  501. - **Origin header validation** — browser requests with a present-but-disallowed `Origin`/`Referer` are rejected. Requests with **no** `Origin` (curl, Postman, MCP-over-HTTP clients) are allowed; Host validation is the defense against rebinding.
  502. - Binds to localhost (127.0.0.1) by default.
  503. - No authentication in current version (OAuth support planned).
  504. **Exposing HTTP mode beyond localhost** — if you bind to a LAN/public address or put the server behind a reverse proxy or public domain, you **must** set `ALLOWED_HOSTS` to the hostname(s) clients will use, otherwise every non-loopback request is rejected with `403`:
  505. ```bash
  506. # Bind to all interfaces and accept the machine's LAN name + a public domain
  507. ALLOWED_HOSTS=my-nas.local,anki.example.com PORT=8080 HOST=0.0.0.0 node dist/main-http.js
  508. ```
  509. When you bind to `0.0.0.0`/`::` without `ALLOWED_HOSTS`, the server logs a startup warning that only loopback `Host` headers will be accepted.
  510. > **Docker / reverse proxy / public domain:** the same rule applies. In Docker, requests usually arrive with the container's published hostname or the proxy's `Host`, so set `ALLOWED_HOSTS` accordingly. A reverse proxy (nginx, Caddy, Traefik) should either forward the original `Host` and have that hostname listed in `ALLOWED_HOSTS`, or rewrite the upstream `Host` to `localhost`. The built-in `--ngrok` integration handles this automatically (see below).
  511. **Example: Running Modes**
  512. ```bash
  513. # Development - STDIO mode (watch mode with auto-rebuild)
  514. npm run start:dev:stdio
  515. # Development - HTTP mode (watch mode with auto-rebuild)
  516. npm run start:dev:http
  517. # Production - STDIO mode
  518. npm run start:prod:stdio
  519. # or
  520. node dist/main-stdio.js
  521. # Production - HTTP mode
  522. npm run start:prod:http
  523. # or
  524. PORT=8080 HOST=0.0.0.0 node dist/main-http.js
  525. ```
  526. ### Building an MCPB Bundle
  527. To create a distributable MCPB bundle:
  528. ```bash
  529. npm run mcpb:bundle
  530. ```
  531. This command will:
  532. 1. Sync version from `package.json` to `manifest.json`
  533. 2. Remove old `.mcpb` files
  534. 3. Build the TypeScript project
  535. 4. Package `dist/` and `node_modules/` into an `.mcpb` file
  536. 5. Run `mcpb clean` to remove devDependencies (optimizes bundle from ~47MB to ~10MB)
  537. The output file will be named `anki-mcp-server-X.X.X.mcpb` and can be distributed for one-click installation.
  538. #### What Gets Bundled
  539. The MCPB bundle includes:
  540. - Compiled JavaScript (`dist/` directory - includes all three entry points)
  541. - Production dependencies only (`node_modules/` - devDependencies removed by `mcpb clean`)
  542. - Package metadata (`package.json`)
  543. - Manifest configuration (`manifest.json` - configured to use `main-stdio.js`)
  544. - Icon (`icon.png`)
  545. Source files, tests, and development configs are automatically excluded via `.mcpbignore`.
  546. ### Logging in Claude Desktop
  547. When running as an MCPB extension in Claude Desktop, logs are written to:
  548. **Log Location**: `~/Library/Logs/Claude/` (macOS)
  549. The logs are split across multiple files:
  550. - **main.log** - General Claude Desktop application logs
  551. - **mcp-server-Anki MCP Server.log** - MCP protocol messages for this extension
  552. - **mcp.log** - Combined MCP logs from all servers
  553. **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:
  554. - Application startup and MCP protocol communication → MCP-specific log
  555. - Server internal logging (pino) → Both MCP-specific log and sometimes main.log
  556. To view logs in real-time:
  557. ```bash
  558. tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log
  559. ```
  560. ### Debugging the MCP Server
  561. You can debug the MCP server using the MCP Inspector and attaching a debugger from your IDE (WebStorm, VS Code, etc.).
  562. **Note for HTTP Mode:** When testing HTTP mode (Streamable HTTP) with MCP Inspector, use "Connection Type: Via Proxy" to avoid CORS errors.
  563. #### Step 1: Configure Debug Server in MCP Inspector
  564. The `mcp-inspector-config.json` already includes a debug server configuration:
  565. ```json
  566. {
  567. "mcpServers": {
  568. "stdio-server-debug": {
  569. "type": "stdio",
  570. "command": "node",
  571. "args": ["--inspect-brk=9229", "dist/main-stdio.js"],
  572. "env": {
  573. "MCP_SERVER_NAME": "anki-mcp-stdio-debug",
  574. "MCP_SERVER_VERSION": "1.0.0",
  575. "LOG_LEVEL": "debug"
  576. },
  577. "note": "Anki MCP server with debugging enabled on port 9229"
  578. }
  579. }
  580. }
  581. ```
  582. #### Step 2: Start the Debug Server
  583. Run the MCP Inspector with the debug server:
  584. ```bash
  585. npm run inspector:debug
  586. ```
  587. This will start the server with Node.js debugging enabled on port 9229 and pause execution at the first line.
  588. #### Step 3: Attach Debugger from Your IDE
  589. ##### WebStorm
  590. 1. Go to **Run → Edit Configurations**
  591. 2. Add a new **Attach to Node.js/Chrome** configuration
  592. 3. Set the port to `9229`
  593. 4. Click **Debug** to attach
  594. ##### VS Code
  595. 1. Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
  596. 2. Select **Debug MCP Server (Attach)** configuration
  597. 3. Press F5 to attach
  598. #### Step 4: Set Breakpoints and Debug
  599. Once attached, you can:
  600. - Set breakpoints in your TypeScript source files
  601. - Step through code execution
  602. - Inspect variables and call stack
  603. - Use the debug console for evaluating expressions
  604. The debugger will work with source maps, allowing you to debug the original TypeScript code rather than the compiled JavaScript.
  605. ### Debugging with Claude Desktop
  606. You can also debug the MCP server while it runs inside Claude Desktop by enabling the Node.js debugger and attaching your IDE.
  607. #### Step 1: Configure Claude Desktop for Debugging
  608. Update your Claude Desktop config to enable debugging:
  609. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  610. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  611. **Linux**: `~/.config/Claude/claude_desktop_config.json`
  612. ```json
  613. {
  614. "mcpServers": {
  615. "anki-mcp": {
  616. "command": "node",
  617. "args": [
  618. "--inspect=9229",
  619. "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
  620. ],
  621. "env": {
  622. "ANKI_CONNECT_URL": "http://localhost:8765"
  623. }
  624. }
  625. }
  626. }
  627. ```
  628. **Key change**: Add `--inspect=9229` before the path to `dist/main-stdio.js`
  629. **Debug options**:
  630. - `--inspect=9229` - Start debugger immediately, doesn't block (recommended)
  631. - `--inspect-brk=9229` - Pause execution until debugger attaches (for debugging startup issues)
  632. #### Step 2: Restart Claude Desktop
  633. After saving the config, restart Claude Desktop. The MCP server will now run with debugging enabled on port 9229.
  634. #### Step 3: Attach Debugger from Your IDE
  635. ##### WebStorm
  636. 1. Go to **Run → Edit Configurations**
  637. 2. Click the **+** button and select **Attach to Node.js/Chrome**
  638. 3. Configure:
  639. - **Name**: `Attach to Anki MCP (Claude Desktop)`
  640. - **Host**: `localhost`
  641. - **Port**: `9229`
  642. - **Attach to**: `Node.js < 8` or `Chrome or Node.js > 6.3` (depending on WebStorm version)
  643. 4. Click **OK**
  644. 5. Click **Debug** (Shift+F9) to attach
  645. ##### VS Code
  646. 1. Add to `.vscode/launch.json`:
  647. ```json
  648. {
  649. "version": "0.2.0",
  650. "configurations": [
  651. {
  652. "type": "node",
  653. "request": "attach",
  654. "name": "Attach to Anki MCP (Claude Desktop)",
  655. "port": 9229,
  656. "skipFiles": ["<node_internals>/**"],
  657. "sourceMaps": true,
  658. "outFiles": ["${workspaceFolder}/dist/**/*.js"]
  659. }
  660. ]
  661. }
  662. ```
  663. 2. Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
  664. 3. Select **Attach to Anki MCP (Claude Desktop)**
  665. 4. Press F5 to attach
  666. #### Step 4: Debug in Real-Time
  667. Once attached, you can:
  668. - Set breakpoints in your TypeScript source files (e.g., `src/mcp/primitives/essential/tools/create-model.tool.ts`)
  669. - Use Claude Desktop normally - breakpoints will hit when tools are invoked
  670. - Step through code execution
  671. - Inspect variables and call stack
  672. - Use the debug console
  673. **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!
  674. **Note**: The debugger stays attached as long as Claude Desktop is running. You can detach/reattach anytime without restarting Claude Desktop.
  675. ### Build Commands
  676. ```bash
  677. npm run build # Build the project (compile TypeScript to JavaScript)
  678. npm run start:dev:stdio # STDIO mode with watch (auto-rebuild)
  679. npm run start:dev:http # HTTP mode with watch (auto-rebuild)
  680. npm run type-check # Run TypeScript type checking
  681. npm run lint # Run ESLint
  682. npm run mcpb:bundle # Sync version, clean, build, and create MCPB bundle
  683. ```
  684. ### NPM Package Testing (Local)
  685. Test the npm package locally before publishing:
  686. ```bash
  687. # 1. Create local package
  688. npm run pack:local # Builds and creates @ankimcp/anki-mcp-server-*.tgz
  689. # 2. Install globally from local package
  690. npm run install:local # Installs from ./@ankimcp/anki-mcp-server-*.tgz
  691. # 3. Test the command
  692. ankimcp # Runs HTTP server on port 3000
  693. # 4. Uninstall when done testing
  694. npm run uninstall:local # Removes global installation
  695. ```
  696. **How it works:**
  697. - `npm pack` creates a `.tgz` file identical to what npm publish would create
  698. - Installing from `.tgz` simulates what users get from `npm install -g ankimcp`
  699. - This lets you test the full user experience before publishing to npm
  700. ### Testing Commands
  701. ```bash
  702. npm test # Run all tests
  703. npm run test:unit # Run unit tests only
  704. npm run test:tools # Run tool-specific tests
  705. npm run test:workflows # Run workflow integration tests
  706. npm run test:e2e # Run end-to-end tests
  707. npm run test:cov # Run tests with coverage report
  708. npm run test:watch # Run tests in watch mode
  709. npm run test:debug # Run tests with debugger
  710. npm run test:ci # Run tests for CI (silent, with coverage)
  711. ```
  712. ### Test Coverage
  713. The project maintains 70% minimum coverage thresholds for:
  714. - Branches
  715. - Functions
  716. - Lines
  717. - Statements
  718. Coverage reports are generated in the `coverage/` directory.
  719. ## Versioning
  720. This project follows [Semantic Versioning](https://semver.org/) with a pre-1.0 development approach:
  721. - **0.x.x** - Beta/Development versions (current phase)
  722. - **0.1.x** - Bug fixes and patches
  723. - **0.2.0+** - New features or minor improvements
  724. - **Breaking changes** are acceptable in 0.x versions
  725. - **1.0.0** - First stable release
  726. - Will be released when the API is stable and tested
  727. - Breaking changes will require major version bumps (2.0.0, etc.)
  728. **Current Status**: `0.27.1` - Active beta development. Recent features include collection-wide review analysis (`review_stats` now aggregates across all decks when `deck` is omitted), model field management (`addModelField`, `removeModelField`, `renameModelField`, `repositionModelField`), 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.
  729. ### MCPB spec evolution
  730. This project targets Anthropic's MCPB bundle specification, which is still evolving. We track the spec at [https://github.com/modelcontextprotocol/mcpb](https://github.com/modelcontextprotocol/mcpb) and may introduce breaking changes to stay compliant. Breaking changes are permitted under the 0.x.x versioning scheme.
  731. ## Similar Projects
  732. If you're exploring Anki MCP integrations, here are other projects in this space:
  733. ### [scorzeth/anki-mcp-server](https://github.com/scorzeth/anki-mcp-server)
  734. - **Status**: Appears to be abandoned (no recent updates)
  735. - Early implementation of Anki MCP integration
  736. ### [nailuoGG/anki-mcp-server](https://github.com/nailuoGG/anki-mcp-server)
  737. - **Approach**: Lightweight, single-file implementation
  738. - **Architecture**: Procedural code structure with all tools in one file
  739. - **Good for**: Simple use cases, minimal dependencies
  740. **Why this project differs:**
  741. - **Enterprise-grade architecture**: Built on NestJS with dependency injection
  742. - **Modular design**: Each tool is a separate class with clear separation of concerns
  743. - **Maintainability**: Easy to extend with new features without touching existing code
  744. - **Testing**: Comprehensive test suite with 70% coverage requirement
  745. - **Type safety**: Strict TypeScript with Zod validation
  746. - **Error handling**: Robust error handling with helpful user feedback
  747. - **Production-ready**: Proper logging, progress reporting, and MCPB bundle support
  748. - **Scalability**: Can easily grow from basic tools to complex workflows
  749. **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.
  750. ## Useful Links
  751. - [Model Context Protocol Documentation](https://modelcontextprotocol.io/docs)
  752. - [AnkiConnect API Documentation](https://git.sr.ht/~foosoft/anki-connect)
  753. - [Claude Desktop Download](https://claude.ai/download)
  754. - [Building Desktop Extensions (Anthropic Blog)](https://www.anthropic.com/engineering/desktop-extensions)
  755. - [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
  756. - [NestJS Documentation](https://docs.nestjs.com)
  757. - [Anki Official Website](https://apps.ankiweb.net/)
  758. ## License & Attribution
  759. This project is licensed under the MIT License — see [LICENSE](LICENSE) for the full text.
  760. Copyright © 2026 Anatoly Tarnavsky.
  761. ### Third-Party Attributions
  762. - **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).
  763. - **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).
  764. - 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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.