Anki MCP

官方

一個MCP伺服器，讓AI助手能與間隔重複閃卡應用程式Anki互動。

GitHub
408

你可以用 Anki MCP 做什麼？

  • 互動式複習到期卡片 — 要求你的助手使用 get_due_cards 取得到期卡片，透過 present_card 呈現，並使用 rate_card 記錄你的評分。
  • 建立並設計自訂筆記類型 — 使用 createModel、updateModelStyling 和 updateModelTemplates 建立具有特定欄位、卡片模板和 CSS 的新筆記類型。
  • 從清單批次新增閃卡 — 提供一組筆記，讓助手使用 addNotes 一次建立所有筆記，並共用相同的牌組和模型。
  • 搜尋並更新現有筆記 — 使用 findNotes 依牌組、標籤或到期狀態尋找筆記，然後使用 updateNoteFields、addTags 或 removeTags 修改其欄位或標籤。
  • 管理收藏中的媒體 — 使用 storeMediaFile 從本機檔案路徑上傳圖片或音訊，透過 getMediaFilesNames 列出已儲存的檔案，或移除未使用的媒體。
  • 開啟 Anki 的圖形介面進行手動編輯 — 使用 guiBrowse 開啟卡片瀏覽器，使用 guiAddCards 預先填入新增卡片對話框，或使用 guiEditNote 編輯特定筆記。

文件

Anki MCP 伺服器

Tests npm version

Anki + MCP Integration

透過 模型上下文協定 (Model Context Protocol) 將 Anki 與 AI 助理無縫整合

Beta - 此專案正處於積極開發階段。API 和功能可能會有所變動。

一個模型上下文協定 (MCP) 伺服器，讓 AI 助理能夠與 Anki（間隔重複抽認卡應用程式）互動。

透過自然語言互動來轉變您的 Anki 體驗——就像擁有一位私人導師。AI 助理不僅僅是呈現問題和答案；它還能解釋概念，讓學習過程更具吸引力和人性化，提供上下文，並適應您的學習風格。它可以即時建立和編輯筆記，將您的學習過程轉變為動態對話。更多功能即將推出！

範例與教學

有關在 Claude Desktop 中使用此 MCP 伺服器的綜合指南、實際範例和逐步教學，請造訪：

ankimcp.ai - 包含實用範例和使用案例的完整文件

請參閱 docs/ 以獲取補充文件，包括審查者設定指南和範例 Anki 牌組。

使用案例範例

三個代表性的提示，展示了此伺服器啟用的工具流程：

  1. 「幫我複習我的西班牙語牌組。」 — 助理與 AnkiWeb 同步 (sync)，擷取到期卡片 (get_due_cards 搭配牌組篩選器)，呈現每張卡片 (present_card)，並記錄您的評分 (rate_card)。為您量身打造的自然學習對話與解釋。

  2. 「建立 10 張帶有 RTL 樣式的阿拉伯語單字卡。」 — 助理列出筆記類型 (modelNames)，如有需要則建立自訂 RTL 模型 (createModel + updateModelStyling 用於從右到左的 CSS)，然後批次建立卡片 (addNotes)。

  3. 「將我下載資料夾中的這張圖片匯入到所選筆記的正面。」 — 助理上傳本機檔案 (storeMediaFile 搭配檔案路徑)，從瀏覽器讀取目前選取的筆記 (guiSelectedNotes + notesInfo)，並使用 <img> 標籤更新正面欄位 (updateNoteFields)。

可用工具

伺服器公開了 42 個 MCP 工具 — 31 個用於日常 Anki 操作的基本工具，以及 11 個用於驅動 Anki 桌面介面以進行筆記編輯/建立工作流程的 GUI 工具。

基本工具

複習與學習

  • sync - 與 AnkiWeb 同步，以拉取最新資料並推送變更
  • get_due_cards - 取得到期需複習的卡片，可選擇按牌組篩選
  • get_cards - 取得卡片，可按狀態（到期、新、學習中、暫停、隱藏）和牌組進行靈活篩選
  • present_card - 顯示一張卡片以供複習，包含其問題/正面
  • rate_card - 評分卡片表現（再次、困難、良好、簡單）並安排下次複習

注意： 卡片 front/back 內容是根據其自身的範本（如 Anki 所示）為每張卡片呈現的，因此反轉和填空卡片會顯示正確的方向。您的卡片範本所新增的靜態文字也會出現在輸出中。

牌組管理

  • listDecks - 列出所有牌組，可選擇包含每個牌組的卡片數量統計
  • deckStats - 取得單一牌組的綜合統計資料（數量、難易度/間隔分佈）
  • createDeck - 建立一個新的空牌組（支援 Parent::Child，最多 2 層）
  • changeDeck - 將卡片移至不同的牌組（若不存在則建立）

筆記管理

  • addNote - 使用指定的欄位和標籤建立單一筆記
  • addNotes - 批次建立最多 100 張共用牌組和模型的筆記（支援部分成功）
  • findNotes - 使用 Anki 查詢語法搜尋筆記（deck:、tag:、is:due 等）
  • notesInfo - 取得筆記的詳細資訊（欄位、標籤、CSS 樣式）
  • updateNoteFields - 更新現有筆記欄位（支援 CSS，支援 HTML 內容）
  • deleteNotes - 刪除筆記及其所有相關卡片（破壞性操作，需要確認）

標籤管理

  • getTags - 取得集合中的所有標籤（請先使用以避免重複）
  • addTags - 將以空格分隔的標籤新增至指定的筆記
  • removeTags - 從指定的筆記中移除以空格分隔的標籤
  • replaceTags - 在指定的筆記中重新命名標籤
  • clearUnusedTags - 移除未被任何筆記使用的孤立標籤（破壞性操作）

媒體管理

  • getMediaFilesNames - 列出 collection.media 中的媒體檔案，可選擇按模式篩選
  • retrieveMediaFile - 以 base64 內容下載媒體檔案
  • storeMediaFile - 從 base64 資料、絕對檔案路徑或 URL 上傳媒體
  • deleteMediaFile - 從 collection.media 移除媒體檔案（破壞性操作）

💡 圖片最佳實踐：

  • ✅ 使用檔案路徑（例如 /Users/you/image.png）- 快速且高效
  • ✅ 使用 URL（例如 https://example.com/image.jpg）- 直接下載
  • ❌ 避免使用 base64 - 極其緩慢且耗費 token

只需告訴 Claude 圖片在哪裡，它就會自動使用最有效的方法處理上傳。

模型/範本管理

  • modelNames - 列出所有可用的筆記類型/模型
  • modelFieldNames - 取得特定筆記類型的欄位名稱
  • modelStyling - 取得筆記類型的 CSS 樣式資訊
  • modelTemplates - 取得筆記類型的卡片範本（正面和背面 HTML）
  • createModel - 使用自訂欄位、卡片範本和 CSS 建立新的筆記類型（例如 RTL 模型）
  • updateModelStyling - 更新現有筆記類型的 CSS 樣式（套用至其所有卡片）
  • updateModelTemplates - 更新現有筆記類型的卡片範本（正面和背面 HTML）（套用至其所有卡片）
  • addModelField - 將新欄位新增至現有筆記類型（附加在末尾或插入在特定位置）
  • removeModelField - 從現有筆記類型中移除欄位（從所有筆記中刪除其內容；需要明確確認）
  • renameModelField - 重新命名現有筆記類型中的欄位（引用舊名稱的卡片範本必須單獨更新）
  • repositionModelField - 變更現有筆記類型中欄位的位置

統計資料

  • collection_stats - 所有牌組的彙總統計資料，包含每個牌組的細目
  • review_stats - 複習歷史分析（時間模式、記憶保留指標、學習連續紀錄）

GUI 工具

驅動 Anki 桌面介面的工具。適用於筆記編輯/建立和牌組管理工作流程，不適用於複習階段。

  • guiBrowse - 開啟卡片瀏覽器並搜尋卡片
  • guiSelectCard - 在卡片瀏覽器中選取特定卡片
  • guiSelectedNotes - 取得目前在卡片瀏覽器中選取的筆記 ID
  • guiAddCards - 開啟「新增卡片」對話框，並預先填入筆記詳細資料
  • guiEditNote - 開啟特定筆記的筆記編輯器
  • guiDeckOverview - 開啟特定牌組的牌組概覽對話框
  • guiDeckBrowser - 開啟牌組瀏覽器對話框
  • guiCurrentCard - 取得複習模式中目前卡片的資訊
  • guiShowQuestion - 顯示目前卡片的問題面
  • guiShowAnswer - 顯示目前卡片的答案面
  • guiUndo - 復原 Anki 中的上一個動作

先決條件

安裝

有幾種方法可以將伺服器安裝到您的電腦上。安裝完成後，請前往連接 AI 客戶端將其連接到您的 AI 助理——無論是本機還是遠端。

npm（全域或 npx）

安裝伺服器的通用方法，適用於任何直接啟動它的 MCP 客戶端。

為執行 ankimcp 命令的客戶端進行全域安裝：

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

或無需安裝即可隨需執行：

npx @ankimcp/anki-mcp-server

MCPB 套件（建議用於 Claude Desktop）

為 Claude Desktop 安裝此 MCP 伺服器的最簡單方法：

  1. 從 Releases 頁面下載最新的 .mcpb 套件
  2. 在 Claude Desktop 中安裝擴充功能：
    • 方法 1：前往「設定」→「擴充功能」，然後拖放 .mcpb 檔案
    • 方法 2：前往「設定」→「開發者」→「擴充功能」→「安裝擴充功能」，然後選取 .mcpb 檔案
  3. 如有需要，設定 AnkiConnect URL（預設為 http://localhost:8765）
  4. 重新啟動 Claude Desktop

就是這樣！該套件包含了在本機執行伺服器所需的一切。

給 Anthropic MCP 目錄審查者的話： 在 docs/reviewer-setup.md 中提供了一個從零到整合的逐步解說，其中包含一個預先填入的範例牌組。

從原始碼安裝（用於開發）

用於開發或進階用途：

npm install
npm run build

連接 AI 客戶端

AI 助理可以透過兩種方式連接到此伺服器，具體取決於助理的執行位置：

  • 本機 — 伺服器與 AI 客戶端（Claude Desktop、Cursor、Cline、Zed 或本機瀏覽器工作階段）在同一台電腦上執行。對於桌面 MCP 客戶端使用 STDIO，對於本機網頁工具使用 HTTP。
  • 遠端 — 託管/遠端 AI（例如雲端中的 ChatGPT 或 Claude.ai）需要連接到在您本機電腦上執行的 Anki。使用受管理的 通道 (Tunnel)（✅ 建議 — 已驗證），或作為更輕量級的未驗證替代方案，使用 ngrok。

本機

伺服器與您的 AI 客戶端在同一台電腦上執行，並與 localhost 上的 AnkiConnect 通訊。

STDIO（主要本機整合）

STDIO 是本機桌面 MCP 客戶端的標準傳輸方式 — Claude Desktop、Cursor IDE、Cline、Zed Editor 等。客戶端將伺服器作為子程序啟動，並透過標準輸入/輸出進行通訊。

支援的客戶端：

  • Claude Desktop
  • Cursor IDE - AI 驅動的程式碼編輯器
  • Cline - 用於 AI 輔助的 VS Code 擴充功能
  • Zed Editor - 快速、現代的程式碼編輯器
  • 其他支援 STDIO 傳輸的 MCP 客戶端

對於 Claude Desktop，MCPB 套件是最簡單的途徑。對於其他客戶端，請使用 --stdio 旗標設定 npm 套件。

設定 - 選擇一種方法：

方法 1：使用 npx（建議 - 無需安裝）

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

方法 2：使用全域安裝

首先，進行全域安裝：

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

然後進行設定：

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

設定檔位置：

  • Cursor IDE：~/.cursor/mcp.json (macOS/Linux) 或 %USERPROFILE%\.cursor\mcp.json (Windows)
  • Cline：可透過 VS Code 中的設定 UI 存取
  • Zed Editor：透過擴充功能市集安裝為 MCP 擴充功能

有關客戶端特定功能和疑難排解，請查閱您的 MCP 客戶端文件。另請參閱連接到 Claude Desktop 以獲取直接指向已建置的 dist/main-stdio.js 的設定。

HTTP（本機網頁 AI）

HTTP 模式將伺服器作為本機網頁伺服器執行，使用 MCP 可串流 HTTP 協定。這是網頁 AI 工具指向您的電腦時所通訊的傳輸方式，也是遠端選項向外部世界公開的內容。就其本身而言，HTTP 模式僅綁定到 localhost。

綁定到 localhost 之外？ 如果您傳遞 --host 0.0.0.0（或在反向代理/公開網域後執行），伺服器預設僅接受回送 Host 標頭以進行 DNS 重新綁定保護 — 請將 ALLOWED_HOSTS 設定為客戶端使用的主機名稱。請參閱 HTTP 模式設定。

設定 - 選擇一種方法：

方法 1：使用 npx（建議 - 無需安裝）

# Quick start
npx @ankimcp/anki-mcp-server

# 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

方法 2：使用全域安裝

# Install once
npm install -g @ankimcp/anki-mcp-server

# Run the server
ankimcp

# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765

方法 3：從原始碼安裝（用於開發）

npm install
npm run build
npm run start:prod:http

若要讓雲端託管的 AI 能夠存取本機 HTTP 伺服器，請使用下方的遠端選項之一。

遠端

託管/遠端 AI（例如在雲端執行的 ChatGPT 或 Claude.ai）無法直接連線到 localhost。這些選項會將您的本機 Anki 公開到網際網路，以便遠端助理可以與之通訊。

通道（✅ 建議）

建議的遠端路徑 — 已驗證且安全。 與原始公開連接埠不同，通道模式要求您登入（OAuth 2.0 裝置流程），因此端點不會對任何猜中 URL 的人開放。

通道模式讓網頁型 AI 助理無需自行執行通道，即可存取您的本機 Anki。伺服器會透過 WebSocket 向外連線到受管理的 AnkiMCP 通道服務 (wss://tunnel.ankimcp.ai)，並獲派一個公開 URL。驗證機制已內建 — 無需 ngrok 帳戶或獨立的通道程序，且您只需登入一次。

登入（OAuth 裝置流程）：

通道模式使用 OAuth 2.0 裝置授權授予。登入時會自動在瀏覽器中開啟一個核准頁面，代碼已嵌入 URL 中 — 無需輸入任何內容，只需核准即可。（如果無法開啟瀏覽器，終端機會列印驗證 URL 和代碼，作為手動輸入的備用方案。）成功後，憑證會儲存到 ~/.ankimcp/credentials.json（檔案權限 0600）。

# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
ankimcp --login
npx @ankimcp/anki-mcp-server --login

# Clear saved credentials
ankimcp --logout

啟動通道：

# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
ankimcp --tunnel
npx @ankimcp/anki-mcp-server --tunnel

# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
ankimcp --tunnel wss://my-tunnel.example.com

如果沒有憑證，--tunnel 會自動先啟動登入流程，然後繼續建立通道。此自動登入需要互動式終端機 — 當 stdout 不是 TTY 時（systemd、無頭 Docker、CI），伺服器會快速失敗，並要求您先執行 ankimcp --login。連線後，會列印公開的通道 URL；按下 Ctrl+C 即可中斷連線。將該 URL 分享給您的 AI 助理。

通道模式環境變數：

變數說明預設值
TUNNEL_SERVER_URL通道伺服器 WebSocket URL（--tunnel/--login 旗標值會覆寫此設定）wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_ID裝置流程的 OAuth 用戶端 ID。進階 — 僅在指向自行託管的通道/驗證服務時需要。（內建）

裝置流程驗證端點 (/auth/device、/auth/token) 衍生自 TUNNEL_SERVER_URL，因此將 --tunnel（或 TUNNEL_SERVER_URL）指向不同的主機，也會將驗證移至該主機。

運作方式： 通道模式在記憶體內傳輸後方，於同程序中執行 MCP 伺服器（McpModule 啟動時不帶內建傳輸）。TunnelMcpService 將該記憶體內傳輸連接到 MCP 伺服器，而 TunnelClient 則透過 WebSocket 將其橋接到遠端通道服務 — 向內轉送 MCP 請求，向外轉送回應。AnkiConnect 仍然只會在本機上被存取。

ngrok（未驗證的替代方案）

如果您希望在不使用受管理通道帳戶的情況下，公開地公開本機 HTTP 模式，內建的 --ngrok 旗標會啟動一個 ngrok 子程序 (src/services/ngrok.service.ts)，並在啟動橫幅中列印公開 URL：

# One-time ngrok setup, then:
ankimcp --ngrok

此路徑未經驗證 — 任何擁有該 URL 的人都可以存取您的 Anki，因此安全性低於通道。除非您有特定理由需要管理自己的 ngrok 端點，否則請優先使用通道。（需要全域安裝 ngrok 和 authtoken。）

--ngrok 旗標會使用 --host-header=rewrite 啟動 ngrok，因此 ngrok 會在轉送前將上游的 Host 改寫為 localhost。這樣可以讓請求保持在迴路主機允許清單內（請參閱 DNS 重新綁定防護），而無需將公開的 *.ngrok 網域新增到 ALLOWED_HOSTS。如果您改為手動執行 ngrok，請使用相同的旗標 — ngrok http --host-header=rewrite 3000 — 否則 ngrok 會將公開的 ngrok 主機名稱作為 Host 轉送，伺服器會以 403 拒絕該請求。

CLI 選項（所有模式）

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -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)
  --read-only                    Run in read-only mode (blocks all write operations)
  --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 --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

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 --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

唯讀模式（所有模式）

--read-only 旗標可防止對您的 Anki 集合進行任何修改。啟用時：

  • 所有讀取操作均可正常運作（瀏覽牌組、檢視卡片、搜尋筆記）
  • 允許複習操作（同步、answerCards、suspend/unsuspend）
  • 封鎖內容修改（addNote、deleteNotes、createDeck、updateNoteFields 等）
  • 適用於安全地探索 Anki 資料，而無意外變更的風險
# HTTP mode with read-only
ankimcp --read-only

# STDIO mode with read-only
ankimcp --stdio --read-only

# Can combine with other flags
ankimcp --ngrok --read-only

您也可以透過環境變數啟用唯讀模式：

READ_ONLY=true ankimcp

或在 MCP 用戶端設定中：

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

連線到 Claude Desktop（本機模式）

您可以透過以下任一方式在 Claude Desktop 中設定伺服器：

  • 前往：設定 → 開發人員 → 編輯設定
  • 或手動編輯設定檔

設定

將以下內容新增到您的 Claude Desktop 設定：

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

將 /path/to/anki-mcp-server 替換為您的實際專案路徑。

設定檔位置

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • Linux：~/.config/Claude/claude_desktop_config.json

如需更多詳細資訊，請參閱官方 MCP 文件。

環境變數（選用）

變數說明預設值
ANKI_CONNECT_URLAnkiConnect URLhttp://localhost:8765
ANKI_CONNECT_API_VERSIONAPI 版本6
ANKI_CONNECT_API_KEY若在 AnkiConnect 中設定的 API 金鑰-
ANKI_CONNECT_TIMEOUT請求逾時（毫秒）5000
READ_ONLY啟用唯讀模式（true 或 1）false
ALLOWED_HOSTSHTTP 模式：除了迴路之外要接受的額外 Host 標頭值（以逗號分隔的主機名稱）。在繫結到 LAN/公開位址或在反向代理後方執行時為必要。請參閱 HTTP 模式設定。僅限迴路
ALLOWED_ORIGINSHTTP 模式：以逗號分隔的瀏覽器 Origin/Referer 模式允許清單（支援萬用字元，例如 https://*.ngrok.io）。http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URL通道伺服器 WebSocket URL（僅限通道模式）wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPES允許檔案路徑匯入的額外 MIME 類型（以逗號分隔，例如 application/pdf）-
MEDIA_IMPORT_DIR將檔案路徑匯入限制在此目錄-
MEDIA_ALLOWED_HOSTS允許 URL 匯入的特定私人網路主機（以逗號分隔，例如 192.168.1.50,my-nas）-

使用範例

搜尋和更新筆記

# 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 查詢語法範例

findNotes 工具支援 Anki 強大的查詢語法：

  • "deck:DeckName" - 特定牌組中的所有筆記
  • "tag:important" - 帶有 "important" 標籤的筆記
  • "is:due" - 到期需複習的卡片
  • "is:new" - 尚未學習的新卡片
  • "added:7" - 最近 7 天內新增的筆記
  • "front:hello" - 正面欄位中包含 "hello" 的筆記
  • "flag:1" - 帶有紅色旗標的筆記
  • "prop:due<=2" - 2 天內到期的卡片
  • "deck:Spanish tag:verb" - 西班牙語牌組中帶有 verb 標籤的筆記（AND）
  • "deck:Spanish OR deck:French" - 來自任一牌組的筆記

重要注意事項

CSS 和 HTML 處理

  • notesInfo 工具會傳回 CSS 樣式資訊，以便正確呈現感知
  • updateNoteFields 工具支援欄位中的 HTML 內容，並保留 CSS 樣式
  • 每個筆記模型都有自己的 CSS 樣式 - 使用 modelStyling 取得模型特定的 CSS

更新警告

⚠️ 重要：使用 updateNoteFields 時，請勿在 Anki 的瀏覽器中檢視筆記，否則欄位將無法正確更新。更新前請關閉瀏覽器或切換到不同的筆記。如需更多詳細資訊，請參閱已知問題。

刪除安全

deleteNotes 工具需要明確確認 (confirmDeletion: true) 以防止意外刪除。刪除筆記會永久移除所有相關聯的卡片。

安全性

媒體檔案路徑和 URL 驗證

媒體工具 (storeMediaFile、retrieveMediaFile、deleteMediaFile) 和 updateNoteFields 音訊/圖片欄位包含安全性驗證，以防止透過提示注入的濫用：

  • 檔案路徑匯入僅限於媒體檔案類型（圖片、音訊、影片）。非媒體檔案（例如 SSH 金鑰、憑證、shell 設定）會根據 MIME 類型被拒絕。設定 MEDIA_ALLOWED_TYPES 以允許其他檔案類型，或設定 MEDIA_IMPORT_DIR 將匯入限制在特定目錄。
  • URL 匯入會針對 SSRF 攻擊進行驗證。對私人網路（10.x、172.16.x、192.168.x）、迴路（127.x）、連結本機（169.254.x）和非 HTTP(S) 協定的請求會被封鎖。設定 MEDIA_ALLOWED_HOSTS 以允許特定的私人網路主機。
  • 檔案名稱會經過清理，以防止路徑遍歷（例如，../../ 序列會被移除）。

這些保護措施適用於 storeMediaFile、retrieveMediaFile、deleteMediaFile 和 updateNoteFields 音訊/圖片欄位。

路徑遍歷漏洞由 Hideaki Takahashi 回報。

DNS 重新綁定防護（HTTP 傳輸）

在 HTTP 模式下執行時，伺服器會驗證每個請求上的 Host 標頭。預設情況下，無論連接埠為何，僅接受迴路主機（localhost、127.0.0.1、::1）。Host 是瀏覽器禁止的標頭，因此惡意網頁無法偽造它 — 這關閉了 DNS 重新綁定路徑，在該路徑中，重新綁定的頁面會使用偽造的 Host 且沒有 Origin 來存取本機伺服器，並存取 MCP 工具。不允許的 Host 會被拒絕，並顯示 403。

如果您繫結到 0.0.0.0、在反向代理後方執行，或公開一個公開的通道網域，請設定 ALLOWED_HOSTS（以逗號分隔的主機名稱）以允許這些主機。使用 ngrok 建立通道時，伺服器會使用 --host-header=rewrite，因此上游仍然會看到迴路的 Host。請參閱 HTTP 模式設定以取得完整的選項清單。

DNS 重新綁定漏洞由 avishaigo-commits 和 yotampe-pluto 回報。

隱私權政策

此 MCP 伺服器在您的本機上執行，不會收集任何遙測、分析或使用資料。

完整政策：https://ankimcp.ai/privacy/

  • 資料收集：伺服器不收集任何內容。它會在您的 AI 助理和本機 AnkiConnect 外掛程式之間代理請求。
  • 使用 / 儲存：無伺服器端儲存。所有閃卡資料都保留在您自己裝置上的 Anki 安裝中。
  • 第三方分享：無。伺服器僅與您設定的 AnkiConnect URL 通訊（預設：localhost）。如果您啟用 Anki 內建的 AnkiWeb 同步，那會直接在您的 Anki 安裝和 AnkiWeb 之間進行 — 不在此伺服器的範圍內。
  • 保留：不適用 — 伺服器端不保留任何資料。
  • 聯絡方式：support@ankimcp.ai

已知問題

如需已知問題和限制的完整清單，請造訪我們的文件：

已知問題文件

重大限制

在瀏覽器中檢視時筆記更新失敗

⚠️ 重要：使用 updateNoteFields 更新筆記時，如果該筆記目前正在 Anki 的瀏覽器視窗中被檢視，更新將會靜默失敗。這是上游 AnkiConnect 的限制。

解決方法：更新前，請務必關閉瀏覽器或導覽到不同的筆記。

如需更多詳細資訊和其他已知問題，請參閱完整文件。

疑難排解

ERR_REQUIRE_ESM 錯誤

如果您看到類似以下的錯誤：

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

這表示您的 Node.js 版本不受支援。伺服器需要 Node.js 22.12.0+。

注意： 最低支援的執行環境為 Node.js 22.12.0。Node.js 20 (Iron) 已於 2026-04-30 終止支援，不再提供服務。

檢查您的版本：

node --version

解決方案： 將 Node.js 更新至 22.12.0 或更高版本。您可以從 nodejs.org 下載，或使用如 nvm 等版本管理器。

開發

傳輸模式

此伺服器透過獨立的進入點支援三種 MCP 傳輸模式：

STDIO 模式（預設）

  • 適用於 Claude Desktop 等本機 MCP 客戶端
  • 使用標準輸入/輸出進行通訊
  • 進入點：dist/main-stdio.js
  • 執行：npm run start:prod:stdio 或 node dist/main-stdio.js
  • MCPB 套件：使用 STDIO 模式

HTTP 模式（可串流的 HTTP）

  • 適用於遠端 MCP 客戶端和基於網頁的整合
  • 使用 MCP 可串流 HTTP 協定
  • 進入點：dist/main-http.js
  • 執行：npm run start:prod:http 或 node dist/main-http.js
  • 預設連接埠：3000（可透過 PORT 環境變數設定）
  • 預設主機：127.0.0.1（可透過 HOST 環境變數設定）
  • MCP 端點：http://127.0.0.1:3000/（根路徑）

通道模式（受管理的 WebSocket 通道）

  • 適用於透過受管理的 AnkiMCP 通道服務、具備內建驗證機制的網頁型 AI 助理
  • MCP 伺服器在記憶體內傳輸後方於處理程序中執行；TunnelMcpService 將其連接至 MCP 伺服器，而 TunnelClient 則透過 WebSocket 將其橋接至通道服務
  • 進入點：dist/main-tunnel.js
  • 執行：node dist/main-tunnel.js --tunnel（或 ankimcp --tunnel）
  • 驗證：ankimcp --login / ankimcp --logout；憑證儲存於 ~/.ankimcp/credentials.json（0600）
  • 開發：npm run start:dev:tunnel（監看模式，執行 --tunnel --debug）

建置

npm run build  # Builds once, creates dist/ with all three entry points

main-stdio.js、main-http.js 和 main-tunnel.js 全都建置到同一個 dist/ 目錄中。請根據您的需求選擇要執行的項目。

HTTP 模式設定

環境變數：

  • PORT - HTTP 伺服器連接埠（預設：3000）
  • HOST - 綁定位址（預設：127.0.0.1，僅限本機）
  • ALLOWED_HOSTS - 以逗號分隔的額外 Host 標頭值，用於接受超出內建迴路位址集合（localhost、127.0.0.1、::1）的請求。僅主機名稱，與連接埠無關。預設：僅限迴路位址。
  • ALLOWED_ORIGINS - 以逗號分隔的瀏覽器 Origin/Referer 模式允許清單；支援萬用字元（例如 https://*.ngrok.io）。預設：http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*。
  • LOG_LEVEL - 記錄層級（預設：info）

安全性：

  • 主機標頭驗證（DNS 重新綁定防護） — 每個 HTTP 請求都必須攜帶符合允許清單的 Host 標頭。預設情況下，無論連接埠為何，僅接受迴路主機（localhost、127.0.0.1、::1）。Host 是瀏覽器禁止的標頭，因此惡意網頁無法偽造它——這關閉了 DNS 重新綁定 路徑，在該路徑中，重新綁定的頁面會使用偽造的 Host 且沒有 Origin 來存取伺服器。不允許的 Host 會被拒絕，並回傳 403。
  • Origin 標頭驗證 — 存在但不被允許的 Origin/Referer 的瀏覽器請求會被拒絕。沒有 Origin 的請求（curl、Postman、MCP-over-HTTP 客戶端）則被允許；主機驗證是防範重新綁定的防禦措施。
  • 預設綁定到本機（127.0.0.1）。
  • 目前版本無驗證機制（計劃支援 OAuth）。

將 HTTP 模式公開到本機以外 — 如果您綁定到區域網路/公開位址，或將伺服器置於反向代理或公開網域之後，您必須將 ALLOWED_HOSTS 設定為客戶端將使用的主機名稱，否則所有非迴路請求都會被拒絕，並回傳 403：

# Bind to all interfaces and accept the machine's LAN name + a public domain
ALLOWED_HOSTS=my-nas.local,anki.example.com PORT=8080 HOST=0.0.0.0 node dist/main-http.js

當您在沒有 ALLOWED_HOSTS 的情況下綁定到 0.0.0.0/:: 時，伺服器會在啟動時記錄一則警告，表示僅接受迴路 Host 標頭。

Docker / 反向代理 / 公開網域： 同樣的規則適用。在 Docker 中，請求通常會帶有容器的已發布主機名稱或代理的 Host，因此請相應地設定 ALLOWED_HOSTS。反向代理（nginx、Caddy、Traefik）應轉發原始的 Host 並將該主機名稱列入 ALLOWED_HOSTS，或將上游的 Host 改寫為 localhost。內建的 --ngrok 整合會自動處理此問題（請參閱下文）。

範例：執行模式

# 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

建置 MCPB 套件

若要建立可散發的 MCPB 套件：

npm run mcpb:bundle

此指令將會：

  1. 從 package.json 同步版本至 manifest.json
  2. 移除舊的 .mcpb 檔案
  3. 建置 TypeScript 專案
  4. 將 dist/ 和 node_modules/ 封裝成一個 .mcpb 檔案
  5. 執行 mcpb clean 以移除 devDependencies（將套件從約 47MB 最佳化至約 10MB）

輸出檔案將命名為 anki-mcp-server-X.X.X.mcpb，並可散發以供一鍵安裝。

套件內容

MCPB 套件包含：

  • 已編譯的 JavaScript（dist/ 目錄 - 包含所有三個進入點）
  • 僅限生產環境相依套件（node_modules/ - devDependencies 已由 mcpb clean 移除）
  • 套件中繼資料（package.json）
  • 資訊清單設定（manifest.json - 設定為使用 main-stdio.js）
  • 圖示（icon.png）

原始碼檔案、測試和開發設定會透過 .mcpbignore 自動排除。

Claude Desktop 中的記錄

在 Claude Desktop 中作為 MCPB 擴充功能執行時，記錄會寫入：

記錄位置：~/Library/Logs/Claude/ (macOS)

記錄會分割到多個檔案中：

  • main.log - 一般的 Claude Desktop 應用程式記錄
  • mcp-server-Anki MCP Server.log - 此擴充功能的 MCP 協定訊息
  • mcp.log - 來自所有伺服器的合併 MCP 記錄

注意：pino 記錄器輸出（來自伺服器程式碼的 INFO、ERROR、WARN 訊息）會傳送到 stderr，並顯示在 MCP 特定的記錄檔中。Claude Desktop 決定哪個記錄檔接收哪些訊息，但通常：

  • 應用程式啟動和 MCP 協定通訊 → MCP 特定記錄
  • 伺服器內部記錄（pino）→ MCP 特定記錄，有時也會在 main.log 中

若要即時檢視記錄：

tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log

偵錯 MCP 伺服器

您可以使用 MCP Inspector 並從您的 IDE（WebStorm、VS Code 等）附加偵錯器來偵錯 MCP 伺服器。

HTTP 模式注意事項： 使用 MCP Inspector 測試 HTTP 模式（可串流 HTTP）時，請使用「連線類型：透過代理」以避免 CORS 錯誤。

步驟 1：在 MCP Inspector 中設定偵錯伺服器

mcp-inspector-config.json 已包含一個偵錯伺服器設定：

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

步驟 2：啟動偵錯伺服器

使用偵錯伺服器執行 MCP Inspector：

npm run inspector:debug

這將在連接埠 9229 上啟用 Node.js 偵錯功能來啟動伺服器，並在第一行暫停執行。

步驟 3：從您的 IDE 附加偵錯器

WebStorm
  1. 前往 Run → Edit Configurations
  2. 新增一個 Attach to Node.js/Chrome 設定
  3. 將連接埠設定為 9229
  4. 點擊 Debug 以附加
VS Code
  1. 開啟偵錯面板（Ctrl+Shift+D / Cmd+Shift+D）
  2. 選取 Debug MCP Server (Attach) 設定
  3. 按下 F5 以附加

步驟 4：設定中斷點並偵錯

附加後，您可以：

  • 在您的 TypeScript 原始碼檔案中設定中斷點
  • 逐步執行程式碼
  • 檢查變數和呼叫堆疊
  • 使用偵錯主控台來評估運算式

偵錯器將與原始碼對應（source maps）搭配使用，讓您可以偵錯原始的 TypeScript 程式碼，而非已編譯的 JavaScript。

使用 Claude Desktop 進行偵錯

您也可以在 MCP 伺服器於 Claude Desktop 內執行時，透過啟用 Node.js 偵錯器並附加您的 IDE 來進行偵錯。

步驟 1：設定 Claude Desktop 以進行偵錯

更新您的 Claude Desktop 設定以啟用偵錯：

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

關鍵變更：在 dist/main-stdio.js 的路徑前加上 --inspect=9229

偵錯選項：

  • --inspect=9229 - 立即啟動偵錯器，不阻塞（建議）
  • --inspect-brk=9229 - 暫停執行直到偵錯器附加（用於偵錯啟動問題）

步驟 2：重新啟動 Claude Desktop

儲存設定後，重新啟動 Claude Desktop。MCP 伺服器現在將在連接埠 9229 上啟用偵錯功能來執行。

步驟 3：從您的 IDE 附加偵錯器

WebStorm
  1. 前往 Run → Edit Configurations
  2. 點擊 + 按鈕並選取 Attach to Node.js/Chrome
  3. 設定：
    • Name：Attach to Anki MCP (Claude Desktop)
    • Host：localhost
    • Port：9229
    • Attach to：Node.js < 8 或 Chrome or Node.js > 6.3（取決於 WebStorm 版本）
  4. 點擊 OK
  5. 點擊 Debug (Shift+F9) 以附加
VS Code
  1. 新增至 .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"]
    }
  ]
}
  1. 開啟偵錯面板（Ctrl+Shift+D / Cmd+Shift+D）
  2. 選取 Attach to Anki MCP (Claude Desktop)
  3. 按下 F5 以附加

步驟 4：即時偵錯

附加後，您可以：

  • 在您的 TypeScript 原始碼檔案中設定中斷點（例如 src/mcp/primitives/essential/tools/create-model.tool.ts）
  • 正常使用 Claude Desktop - 當工具被調用時，中斷點將會命中
  • 逐步執行程式碼
  • 檢查變數和呼叫堆疊
  • 使用偵錯主控台

範例：在 create-model.tool.ts 的第 119 行設定中斷點，然後要求 Claude 建立一個新模型。偵錯器將會在您的中斷點暫停！

注意：只要 Claude Desktop 正在執行，偵錯器就會保持附加狀態。您可以隨時中斷/重新附加，無需重新啟動 Claude Desktop。

建置指令

npm run build              # Build the project (compile TypeScript to JavaScript)
npm run start:dev:stdio    # STDIO mode with watch (auto-rebuild)
npm run start:dev:http     # HTTP mode with watch (auto-rebuild)
npm run type-check         # Run TypeScript type checking
npm run lint               # Run ESLint
npm run mcpb:bundle        # Sync version, clean, build, and create MCPB bundle

NPM 套件測試（本機）

在發布前於本機測試 npm 套件：

# 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

運作方式：

  • npm pack 會建立一個與 npm publish 所建立內容相同的 .tgz 檔案
  • 從 .tgz 安裝可模擬使用者從 npm install -g ankimcp 取得的內容
  • 這讓您可以在發布到 npm 之前測試完整的使用者體驗

測試指令

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)

測試覆蓋率

此專案對以下項目維持 70% 的最低覆蓋率門檻：

  • 分支
  • 函式
  • 行數
  • 陳述式

覆蓋率報告產生在 coverage/ 目錄中。

版本管理

此專案遵循語意化版本，並採用 1.0 版之前的開發方法：

  • 0.x.x - Beta/開發版本（目前階段）

    • 0.1.x - 錯誤修正和修補程式
    • 0.2.0+ - 新功能或次要改進
    • 重大變更在 0.x 版本中是可接受的

  • 1.0.0 - 第一個穩定版本

    • 將在 API 穩定且經過測試後發布
    • 重大變更將需要提升主要版本號（2.0.0 等）

目前狀態：0.22.0 - 活躍的 beta 開發階段。近期功能包括全集合複習分析（review_stats 現在在省略 deck 時會彙總所有牌組）、模型欄位管理（addModelField、removeModelField、renameModelField、repositionModelField）、批次筆記建立（addNotes）、整合式 ngrok 通道（--ngrok 旗標）、媒體檔案管理、模型/範本管理以及全面的牌組統計資料。API 可能會根據回饋和測試而變更。

MCPB 規範演進

此專案目標是 Anthropic 的 MCPB 套件規範，該規範仍在演進中。我們在 https://github.com/modelcontextprotocol/mcpb 追蹤該規範，並可能引入重大變更以保持合規。在 0.x.x 版本管理方案下，允許重大變更。

類似專案

如果您正在探索 Anki MCP 整合，以下是此領域的其他專案：

scorzeth/anki-mcp-server

  • 狀態：似乎已停止維護（近期無更新）
  • Anki MCP 整合的早期實作

nailuoGG/anki-mcp-server

  • 設計取向：輕量級、單檔案實作
  • 架構：程序式程式碼結構，所有工具集中在一個檔案中
  • 適合場景：簡單的使用案例、最低限度的相依性

本專案的差異化優勢：

  • 企業級架構：基於 NestJS 建構，採用依賴注入
  • 模組化設計：每個工具都是獨立的類別，關注點分離清晰
  • 可維護性：無需修改現有程式碼即可輕鬆擴充新功能
  • 測試：全面的測試套件，要求 70% 的覆蓋率
  • 型別安全：嚴格的 TypeScript 搭配 Zod 驗證
  • 錯誤處理：健全的錯誤處理機制，提供有用的使用者回饋
  • 生產就緒：完善的日誌記錄、進度回報與 MCPB 套件支援
  • 可擴展性：能輕易地從基礎工具發展到複雜的工作流程

適用場景：如果您需要一個穩固的基礎來建構進階的 Anki 整合，或是計劃大幅擴充功能，本專案的架構設計能讓長期維護與擴展更加容易。

實用連結

授權與歸屬

本專案採用 MIT 授權條款 — 完整內容請參閱 LICENSE。

版權所有 © 2026 Anatoly Tarnavsky。

第三方歸屬

  • Anki® 是 Ankitects Pty Ltd 的註冊商標。本專案為非官方的第三方工具，與 Ankitects Pty Ltd 無任何關聯、未受其背書或贊助。Anki 標誌的使用是依據引用 Anki 並附上 https://apps.ankiweb.net 連結的替代授權條款。如需官方 Anki 應用程式，請造訪 https://apps.ankiweb.net。

  • Model Context Protocol (MCP) 是 Anthropic 制定的開放標準。MCP 標誌來自官方 MCP 文件儲存庫，並依據 MIT 授權條款使用。如需更多關於 MCP 的資訊，請造訪 https://modelcontextprotocol.io。

  • 這是一個串接 Anki 與 MCP 技術的獨立專案。所有商標、服務標章、商業名稱、產品名稱及標誌均為其各自所有權人的財產。