Anki MCP

官方

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

GitHub
481
試用此 MCP贊助

你可以用 Anki MCP 做什麼？

  • 以對話方式複習到期卡片 — 請助理用 get_due_cards 拉出到期卡片，透過 present_card 逐一呈現，並用 rate_card 記錄你的評分。
  • 建立並批次新增單字卡 — 讓助理用 addNotes 大量建立筆記，必要時可先用 createModel 和 updateModelStyling 建立自訂模型。
  • 搜尋與編輯既有筆記 — 使用 findNotes 搭配 Anki 查詢語法，透過 notesInfo 檢視詳細資料，並用 updateNoteFields 更新欄位。
  • 管理牌組與排程 — 用 createDeck 建立牌組，透過 changeDeck 移動卡片，或使用 setDueDate 和 forgetCards 重新安排卡片複習時間。
  • 將媒體匯入筆記 — 請助理用 storeMediaFile 上傳本機圖片或 URL，並將其嵌入筆記的欄位中。
  • 操作 Anki 圖形介面 — 用 guiBrowse 和 guiEditNote 開啟瀏覽器或編輯器，或透過 guiSelectedNotes 取得目前選取的筆記。

文件

Anki MCP 伺服器

Tests npm version

Anki + MCP Integration

透過 Anki 與 模型上下文協定，將 AI 助手無縫整合

Beta - 本專案正在積極開發中。API 與功能可能有所變更。

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

透過自然語言互動來改變您的 Anki 體驗——就像擁有一位私人導師。AI 助手不只是呈現問題與答案；它還能解釋概念、讓學習過程更具互動性與人性化、提供情境脈絡，並適應您的學習風格。它能即時建立與編輯筆記，將您的學習時段轉變為動態對話。更多功能即將推出！

範例與教學

如需關於將此 MCP 伺服器與 Claude Desktop 搭配使用的完整指南、實際範例與逐步教學，請造訪：

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）。

可用工具

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

基本工具

複習與學習

  • sync - 與 AnkiWeb 同步以擷取最新資料並推送變更
  • get_due_cards - 取得到期複習的卡片，可依牌組篩選（除非 include_answer: true，否則省略答案，預設 false）
  • get_cards - 依狀態（到期、新卡片、學習中、已暫停、已埋藏）與牌組彈性篩選取得卡片（除非 include_answer: true，否則省略答案，預設 false）
  • present_card - 顯示一張卡片供複習，包含其問題/正面
  • rate_card - 評分卡片表現（Again、Hard、Good、Easy）並安排下次複習
  • forgetCards - 將卡片重設為新卡片，捨棄其排程而不記錄複習
  • setDueDate - 重新安排卡片使其在 N 天後到期（"0"、"3-7"、"1!"），不記錄複習

注意： forgetCards 與 setDueDate 會變更排程而不記錄複習，這是它們與 rate_card 的區別。當卡片的排程有誤而非答案有誤時，請使用這些工具：將卡片評為 Again 以將其埋藏得更深，會記錄一次實際失誤並降低其難度係數，永久扭曲未來的排程與您的統計資料。forgetCards 會清除間隔並重新開始該卡片；setDueDate 則保留卡片的歷史記錄，僅移動下次複習時間。

注意： 卡片的 front/back 內容是依每張卡片各自的範本所呈現（如同 Anki 顯示的方式），因此反向與挖空卡片會顯示正確的方向。您的卡片範本所新增的靜態文字也會出現在輸出中。

牌組管理

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

注意： 牌組統計資料有兩種形式。counts 區塊（以及 listDecks 回報的所有內容）反映 Anki 的牌組瀏覽器：今天到期的卡片，受每個牌組的每日新卡片/複習上限限制，且排除已暫停與已埋藏的卡片——因此 review 並非「成熟卡片」，而 other 區塊只是算術餘數（主要是今天未到期的複習卡片加上超過每日上限的新卡片）。如需真實的依狀態總計，請使用 deckStats / collection_stats 上的 states 區塊，它會透過 Anki 搜尋計算 new、learning、review、suspended 與 buried，忽略到期日與每日上限。

筆記管理

  • 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。

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

用於開發或進階用途（執行測試套件需要 Node.js 24.9+——npm 測試腳本會透過 require(esm) 載入僅限 ESM 的 NestJS 12 套件，Jest 僅在該版本以上支援；使用伺服器的執行時期需求仍為 22.12.0+）：

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 中的設定介面存取
  • Zed Editor：透過擴充功能市集安裝為 MCP 擴充功能

如需用戶端特定功能與疑難排解，請參閱您的 MCP 用戶端文件。另請參閱連線至 Claude Desktop 以取得直接指向已建置之 dist/main-stdio.js 的設定。

HTTP（本機網頁型 AI）

HTTP 模式將伺服器作為本機網頁伺服器執行，使用 MCP Streamable HTTP 協定進行通訊。這是網頁型 AI 工具指向您的機器時所連線的傳輸方式，也是 Remote 選項對外暴露的方式。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 伺服器，請使用下列其中一個 Remote 選項。

Remote（遠端）

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

Tunnel（✅ 建議）

建議的遠端路徑 — 已驗證且安全。 與原始公開連接埠不同，隧道模式要求您登入（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）指向不同主機也會將驗證移至該主機。

運作方式： 隧道模式在記憶體傳輸（TunnelTransport）後方以程序內方式執行 MCP 伺服器。該傳輸擁有 MCP 伺服器，並將每個轉送的請求主體轉換為回應，而 TunnelClient 則透過 WebSocket 將其橋接至遠端隧道服務 — 轉送 MCP 請求進出。AnkiConnect 仍僅在您的本機機器上被連線。

協定修訂： 由於隧道以程序內方式連線 MCP 伺服器，隧道模式僅提供 2025 年修訂版的 MCP 協定，而 STDIO 和 HTTP 模式則同時提供 2025 年及較新的 2026-07-28 修訂版。每個工具在兩種方式下行為皆相同 — 但僅支援 2026-07-28 的用戶端會透過隧道收到協定版本錯誤而被拒絕；請為該用戶端執行 STDIO 或 HTTP 模式。

ngrok（未驗證的替代方案）

如果您不想使用受管理隧道的帳戶，而希望公開暴露本機 HTTP 模式，內建的 --ngrok 旗標會啟動 ngrok 子程序（src/services/ngrok.service.ts），並在啟動橫幅中列印公開 URL：

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

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

--ngrok 旗標會以 --host-header=rewrite 啟動 ngrok，因此 ngrok 會在轉送前將上游 Host 重寫為 localhost。這可讓請求保持在迴圈 Host 允許清單內（請參閱 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 <number>            Port to listen on (HTTP mode; default: 3000, or PORT env var)
  -h, --host <address>           Host to bind to (HTTP mode; default: 127.0.0.1, or HOST env var)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765, or ANKI_CONNECT_URL env var)
  --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、暫停／取消暫停）
  • 封鎖內容修改（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
PORTHTTP 模式：監聽連接埠（--port 旗標優先）3000
HOSTHTTP 模式：綁定位址（--host 旗標優先）127.0.0.1
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 模式（預設）

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

HTTP 模式（可串流 HTTP）

  • 適用於遠端 MCP 用戶端和網頁式整合
  • 使用 MCP Streamable 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 伺服器在記憶體傳輸後方的程序中執行；TunnelTransport 擁有 MCP 伺服器，TunnelClient 透過 WebSocket 將其橋接至隧道服務
  • 協定：僅提供 2025 MCP 修訂版（STDIO 和 HTTP 也提供 2026-07-28）
  • 進入點：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，僅限 localhost）
  • 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）

安全性：

  • Host 標頭驗證（DNS 重新綁定保護） — 每個 HTTP 請求都必須攜帶符合允許清單的 Host 標頭。預設僅接受回送主機（localhost、127.0.0.1、::1），無論連接埠為何。Host 是瀏覽器禁止的標頭，因此惡意網頁無法偽造它——這封閉了 DNS 重新綁定 路徑，使重新綁定的頁面無法以偽造的 Host 且沒有 Origin 的方式到達伺服器。不允許的 Host 會以 403 拒絕。
  • Origin 標頭驗證 — 具有存在但不允許的 Origin／Referer 的瀏覽器請求會被拒絕。沒有 Origin 的請求（curl、Postman、MCP-over-HTTP 用戶端）則允許；Host 驗證是針對重新綁定的防禦。
  • 預設綁定到 localhost（127.0.0.1）。
  • 目前版本沒有驗證（OAuth 支援已規劃）。

將 HTTP 模式公開到 localhost 之外 — 如果您綁定到 LAN／公開位址，或將伺服器放在反向代理或公開網域後方，您必須設定 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

當您綁定到 0.0.0.0／:: 而沒有 ALLOWED_HOSTS 時，伺服器會記錄啟動警告，表示僅接受回送 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 中記錄

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

記錄位置：~/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 模式（Streamable HTTP）時，請使用「Connection Type: Via Proxy」以避免 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

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

步驟 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 偵錯

您也可以在 Claude Desktop 內執行 MCP 伺服器時進行偵錯，方法是啟用 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% 的最低覆蓋率門檻：

  • 分支（Branches）
  • 函式（Functions）
  • 行（Lines）
  • 陳述式（Statements）

覆蓋率報告會產生在 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 開發階段。近期功能包括跨集合的複習分析（當省略 deck 時，review_stats 現在會彙總所有牌組）、模型欄位管理（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 技術的獨立專案。所有商標、服務標章、商業名稱、產品名稱和標誌均為其各自所有者的財產。