Anki MCP Server

🚀 Anki MCP Server

本項目是一個基於Model Context Protocol（MCP）的服務器，它能讓AI助手與間隔重複記憶卡片應用Anki進行交互。藉助自然語言交互，能讓你的Anki使用體驗煥然一新，就像擁有一位私人導師。AI助手不只是簡單地展示問題和答案，還能解釋概念、讓學習過程更具吸引力和人性化、提供上下文信息，並適應你的學習風格。它還能即時創建和編輯筆記，將你的學習會話變成動態的對話。更多功能即將推出！

⚠️ 重要提示

本項目已重命名並遷移：

• 包名：anki-mcp-http → @ankimcp/anki-mcp-server
• 命令：anki-mcp-http → ankimcp 或 anki-mcp-server
• 倉庫：anki-mcp/anki-mcp-desktop → ankimcp/anki-mcp-server

舊的 anki-mcp-http 包為了向後兼容會繼續發佈，但已被棄用。請遷移到新的包。

瞭解更多變更信息 →

💡 使用建議

本項目處於積極開發的Beta階段，API和功能可能會發生變化，請謹慎使用。

🚀 快速開始

本MCP服務器處於積極開發的Beta階段，API和功能可能會發生變化。它能讓AI助手與間隔重複記憶卡片應用Anki進行交互。要獲取使用此MCP服務器與Claude Desktop的全面指南、實際示例和分步教程，請訪問： ankimcp.ai - 包含實際示例和用例的完整文檔

✨ 主要特性

• 自然語言交互：將你的Anki體驗轉變為自然語言交互，就像擁有一位私人導師。AI助手不僅能呈現問題和答案，還能解釋概念、使學習過程更具吸引力和人性化、提供上下文信息，並適應你的學習風格。
• 動態筆記管理：可以即時創建和編輯筆記，將學習會話變成動態的對話。
• 多工具支持：提供了豐富的工具，涵蓋複習與學習、卡組管理、筆記管理和媒體管理等多個方面。

📦 安裝指南

此服務器有兩種運行模式：

• 本地模式（STDIO） - 適用於本地計算機上的Claude Desktop（推薦大多數用戶使用）
• 遠程模式（HTTP） - 適用於基於Web的AI助手，如ChatGPT或Claude.ai

選項1：MCPB捆綁包（推薦 - 本地模式）

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

1. 從發佈頁面下載最新的 .mcpb 捆綁包。
2. 在Claude Desktop中安裝擴展：
   • 方法1：轉到設置 → 擴展，然後拖放 .mcpb 文件。
   • 方法2：轉到設置 → 開發者 → 擴展 → 安裝擴展，然後選擇 .mcpb 文件。
3. 如有需要，配置AnkiConnect URL（默認為 http://localhost:8765）。
4. 重啟Claude Desktop。

選項2：使用STDIO的NPM包（適用於其他MCP客戶端）

如果你想將Anki與諸如 Cursor IDE、Cline 或 Zed Editor 等MCP客戶端一起使用，請使用帶有 --stdio 標誌的npm包：

支持的客戶端：

• Cursor IDE - 由AI驅動的代碼編輯器
• Cline - 用於AI輔助的VS Code擴展
• Zed Editor - 快速、現代的代碼編輯器
• 其他支持STDIO傳輸的MCP客戶端

配置 - 選擇一種方法：

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

選項3：HTTP模式（適用於遠程AI助手）

如果你想在瀏覽器中使用Anki與ChatGPT或Claude.ai，請使用此模式，它可以讓基於Web的AI工具連接到你本地的Anki。

工作原理（簡單解釋）：

1. 在你的計算機（安裝了Anki的地方）上運行一個小型服務器。
2. 使用內置的 --ngrok 標誌自動創建一個公共隧道URL。
3. 將該URL分享給ChatGPT或Claude.ai。
4. 現在，AI就可以通過互聯網與你的Anki進行通信了！

v0.8.0新增功能：集成了ngrok支持，使用 --ngrok 標誌，無需單獨運行ngrok！

設置 - 選擇一種方法：

方法1：使用npx（推薦 - 無需安裝）

# 快速開始
npx @ankimcp/anki-mcp-server

# 使用ngrok隧道（推薦用於基於Web的AI）
npx @ankimcp/anki-mcp-server --ngrok

# 使用自定義選項
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765

方法2：全局安裝

# 一次性安裝
npm install -g @ankimcp/anki-mcp-server

# 運行服務器
ankimcp

# 使用ngrok隧道（推薦用於基於Web的AI）
ankimcp --ngrok

# 使用自定義選項
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

選項4：從源代碼手動安裝（本地模式）

適用於開發或高級使用場景：

npm install
npm run build

💻 使用示例

基礎用法

# 搜索特定卡組中的筆記
findNotes(query: "deck:Spanish")

# 獲取筆記的詳細信息
notesInfo(notes: [1234567890, 1234567891])

# 更新筆記的字段（支持HTML內容）
updateNoteFields(note: {
  id: 1234567890,
  fields: {
    "Front": "<b>¿Cómo estás?</b>",
    "Back": "How are you?"
  }
})

# 刪除筆記（需要確認）
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" - 西班牙語卡組中帶有動詞標籤的筆記（AND）
• "deck:Spanish OR deck:French" - 來自任一卡組的筆記

📚 詳細文檔

可用工具

複習與學習

• sync - 與AnkiWeb同步
• get_due_cards - 獲取待複習的卡片
• present_card - 展示待複習的卡片
• rate_card - 對卡片的表現進行評分

卡組管理

• list_decks - 顯示可用的卡組
• createDeck - 創建新的卡組

筆記管理

• addNote - 創建新的筆記
• findNotes - 使用Anki查詢語法搜索筆記
• notesInfo - 獲取筆記的詳細信息（字段、標籤、CSS）
• updateNoteFields - 更新現有筆記的字段（支持CSS，支持HTML）
• deleteNotes - 刪除筆記及其關聯的卡片

媒體管理

• mediaActions - 管理媒體文件（音頻/圖像）
  • storeMediaFile - 從base64數據、文件路徑或URL上傳媒體
  • retrieveMediaFile - 以base64形式下載媒體
  • getMediaFilesNames - 列出媒體文件，可選擇進行模式過濾
  • deleteMediaFile - 刪除媒體文件

💡 圖片使用最佳實踐：

• ✅ 使用文件路徑（例如，/Users/you/image.png） - 快速高效
• ✅ 使用URL（例如，https://example.com/image.jpg） - 直接下載
• ❌ 避免使用base64 - 極其緩慢且消耗大量令牌

模型/模板管理

• modelNames - 列出筆記類型
• modelFieldNames - 獲取筆記類型的字段
• modelStyling - 獲取筆記類型的CSS樣式

環境變量（可選）

屬性	詳情
ANKI_CONNECT_URL	AnkiConnect的URL，默認為 http://localhost:8765
ANKI_CONNECT_API_VERSION	API版本，默認為 6
ANKI_CONNECT_API_KEY	如果在AnkiConnect中配置了API密鑰，則需要設置該變量
ANKI_CONNECT_TIMEOUT	請求超時時間（毫秒），默認為 5000

連接到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文檔。

開發

傳輸模式

此服務器通過單獨的入口點支持兩種MCP傳輸模式：

STDIO模式（默認）

• 適用於本地MCP客戶端，如Claude Desktop
• 使用標準輸入/輸出進行通信
• 入口點：dist/main-stdio.js
• 運行：npm run start:prod:stdio 或 node dist/main-stdio.js
• MCPB捆綁包：使用STDIO模式

HTTP模式（可流式傳輸的HTTP）

• 適用於遠程MCP客戶端和基於Web的集成
• 使用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/（根路徑）

構建

npm run build  # 一次性構建，在dist/目錄中創建兩個入口點

HTTP模式配置

環境變量：

• PORT - HTTP服務器端口（默認：3000）
• HOST - 綁定地址（默認：127.0.0.1，僅本地訪問）
• ALLOWED_ORIGINS - 允許的CORS來源的逗號分隔列表（默認：localhost）
• LOG_LEVEL - 日誌級別（默認：info）

安全：

• 源頭部驗證（防止DNS重綁定攻擊）
• 默認綁定到本地主機（127.0.0.1）
• 當前版本無身份驗證（計劃支持OAuth）

示例：運行模式

# 開發 - STDIO模式（監視模式，自動重建）
npm run start:dev:stdio

# 開發 - HTTP模式（監視模式，自動重建）
npm run start:dev:http

# 生產 - STDIO模式
npm run start:prod:stdio
# 或者
node dist/main-stdio.js

# 生產 - HTTP模式
npm run start:prod:http
# 或者
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 以刪除開發依賴項（將捆綁包從約47MB優化到約10MB）。

輸出文件將命名為 anki-mcp-server-X.X.X.mcpb，可以進行分發以實現一鍵安裝。

捆綁內容

MCPB包包括：

• 編譯後的JavaScript（dist/ 目錄 - 包括兩個入口點）
• 僅生產依賴項（node_modules/ - 通過 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調試MCP服務器，並從你的IDE（WebStorm、VS Code等）附加調試器。

HTTP模式注意事項：使用MCP Inspector測試HTTP模式（可流式傳輸的HTTP）時，使用 "連接類型：通過代理" 以避免CORS錯誤。

步驟1：在MCP Inspector中配置調試服務器

mcp-inspector-config.json 已經包含了一個調試服務器配置：

{
  "mcpServers": {
    "stdio-server-debug": {
      "type": "",
      "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. 轉到 運行 → 編輯配置
2. 添加一個新的 附加到Node.js/Chrome 配置
3. 將端口設置為 9229
4. 點擊 調試 以附加

VS Code

1. 打開調試面板（Ctrl+Shift+D / Cmd+Shift+D）
2. 選擇 調試MCP服務器（附加） 配置
3. 按F5以附加

步驟4：設置斷點並調試

附加後，你可以：

• 在你的TypeScript源文件中設置斷點
• 逐步執行代碼
• 檢查變量和調用棧
• 使用調試控制檯評估表達式

調試器將使用源映射，允許你調試原始的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. 轉到 運行 → 編輯配置
2. 點擊 + 按鈕並選擇 附加到Node.js/Chrome
3. 配置：
   • 名稱：Attach to Anki MCP (Claude Desktop)
   • 主機：localhost
   • 端口：9229
   • 附加到：Node.js < 8 或 Chrome or Node.js > 6.3（取決於WebStorm版本）
4. 點擊 確定
5. 點擊 調試（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"]
    }
  ]
}

2. 打開調試面板（Ctrl+Shift+D / Cmd+Shift+D）
3. 選擇 Attach to Anki MCP (Claude Desktop)
4. 按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              # 構建項目（將TypeScript編譯為JavaScript）
npm run start:dev:stdio    # STDIO模式，監視模式（自動重建）
npm run start:dev:http     # HTTP模式，監視模式（自動重建）
npm run type-check         # 運行TypeScript類型檢查
npm run lint               # 運行ESLint
npm run mcpb:bundle        # 同步版本、清理、構建並創建MCPB捆綁包

NPM包測試（本地）

在發佈之前，在本地測試npm包：

# 1. 創建本地包
npm run pack:local         # 構建並創建 @ankimcp/anki-mcp-server-*.tgz

# 2. 從本地包全局安裝
npm run install:local      # 從 ./@ankimcp/anki-mcp-server-*.tgz 安裝

# 3. 測試命令
ankimcp                    # 在端口3000上運行HTTP服務器

# 4. 測試完成後卸載
npm run uninstall:local    # 移除全局安裝

測試命令

npm test              # 運行所有測試
npm run test:unit     # 僅運行單元測試
npm run test:tools    # 運行特定工具的測試
npm run test:workflows # 運行工作流集成測試
npm run test:e2e      # 運行端到端測試
npm run test:cov      # 運行測試並生成覆蓋率報告
npm run test:watch    # 在監視模式下運行測試
npm run test:debug    # 運行測試並使用調試器
npm run test:ci       # 為CI運行測試（靜默，帶覆蓋率）

測試覆蓋率

項目對以下方面保持最低70%的覆蓋率閾值：

• 分支
• 函數
• 行
• 語句

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

版本控制

本項目遵循語義化版本控制，採用1.0之前的開發方法：

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

  • 0.1.x - 錯誤修復和補丁
  • 0.2.0+ - 新功能或小改進
  • 在0.x版本中，允許進行重大更改

• 1.0.0 - 第一個穩定版本

  • 將在API穩定並經過測試後發佈
  • 重大更改將需要進行主版本升級（2.0.0等）

當前狀態：0.8.0 - 積極的Beta開發階段。新功能包括集成ngrok隧道（--ngrok 標誌）、用於基於證據的抽認卡創建的 twenty_rules 提示、媒體文件管理和改進的提示系統。API可能會根據反饋和測試進行更改。

類似項目

如果你正在探索Anki MCP集成，以下是該領域的其他項目：

scorzeth/anki-mcp-server

• 狀態：似乎已被棄用（近期無更新）
• Anki MCP集成的早期實現

nailuoGG/anki-mcp-server

• 方法：輕量級，單文件實現
• 架構：過程式代碼結構，所有工具都在一個文件中
• 適用場景：簡單用例，依賴項最少

本項目的不同之處：

• 企業級架構：基於NestJS構建，具有依賴注入
• 模塊化設計：每個工具都是一個單獨的類，職責明確
• 可維護性：易於擴展新功能，無需修改現有代碼
• 測試：全面的測試套件，要求70%的覆蓋率
• 類型安全：嚴格的TypeScript，使用Zod驗證
• 錯誤處理：強大的錯誤處理，提供有用的用戶反饋
• 生產就緒：適當的日誌記錄、進度報告和MCPB捆綁包支持
• 可擴展性：可以輕鬆從基本工具擴展到複雜的工作流

用例：如果你需要一個堅實的基礎來構建高級Anki集成或計劃顯著擴展功能，本項目的架構方法使其更易於長期維護和擴展。

有用鏈接

• Model Context Protocol文檔
• AnkiConnect API文檔
• Claude Desktop下載
• 構建桌面擴展（Anthropic博客）
• MCP服務器倉庫
• NestJS文檔
• Anki官方網站

🔧 技術細節

已知問題

如需瞭解已知問題和限制的完整列表，請訪問我們的文檔： 已知問題文檔

關鍵限制

在瀏覽器中查看時筆記更新失敗

⚠️ 重要提示：使用 updateNoteFields 更新筆記時，如果筆記當前正在Anki的瀏覽器窗口中查看，更新將無聲失敗。這是上游AnkiConnect的限制。

解決方法：在更新之前，始終關閉瀏覽器或導航到其他筆記。有關更多詳細信息和其他已知問題，請參閱 完整文檔。

重要注意事項

CSS和HTML處理

• notesInfo 工具返回CSS樣式信息，以確保正確渲染。
• updateNoteFields 工具支持字段中的HTML內容，並保留CSS樣式。
• 每個筆記模型都有自己的CSS樣式 - 使用 modelStyling 獲取特定模型的CSS。

更新警告

⚠️ 重要提示：使用 updateNoteFields 時，在更新期間請勿在Anki的瀏覽器中查看筆記，否則字段將無法正確更新。在更新之前關閉瀏覽器或切換到其他筆記。有關更多詳細信息，請參閱 已知問題。

刪除安全

deleteNotes 工具需要明確確認（confirmDeletion: true），以防止意外刪除。刪除筆記將永久刪除所有關聯的卡片。

📄 許可證

本項目根據GNU Affero通用公共許可證v3.0或更高版本（AGPL-3.0或更高版本）許可。

為什麼選擇AGPL-3.0？

選擇此許可證是為了在未來可能的集成場景中與Anki的AGPL-3.0許可證保持兼容。

這意味著：

• 個人使用：可以自由使用該軟件。
• 為他人提供服務：必須提供源代碼訪問（AGPL第13節）。
• 修改和分發：必須在AGPL-3.0或更高版本下分享你的改進。

有關完整的許可條款，請參閱 LICENSE 文件。

第三方歸屬

• 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技術。所有商標、服務標誌、商號、產品名稱和標誌均為其各自所有者的財產。