ankimcp/anki-mcp-server

Anki MCP 服务器 – 概述

Anki MCP 服务器是一个实现 Model Context Protocol（MCP）的 Node‑JS 服务。它位于 AI 助手（Claude、Cursor、Cline、Zed 等）和 Anki 间隔重复应用（通过 AnkiConnect 插件）之间。通过暴露丰富的“工具”集——例如列出牌组、获取到期卡片、创建笔记、上传媒体，甚至驱动 Anki 桌面窗口的 GUI 命令——该服务器让语言模型可以像对话式导师一样与您的个人闪卡收藏交互。

存在原因

• AI 驱动学习 – 无需离开聊天，即可要求助手复习牌组、生成新卡片或添加图片。
• 标准化传输 – MCP 定义了 JSON‑over‑STDIO 或 HTTP API，许多 AI 客户端产品已经理解。
• 与 Anki 分离 – 服务器在 Anki 外部运行，因此任何可以启动子进程或调用本地 Web 服务器的 AI 客户端都可以使用它。

何时使用此仓库与插件

• 对于最简单的一体化体验（HTTP、远程隧道、无需 Node.js），使用 AnkiMCP 插件（安装在 Anki 内部）。
• 当您需要以下功能时，使用此独立服务器：
  • STDIO 传输 – Claude Desktop、Cursor、Cline、Zed 等需要。
  • MCPB 捆绑包 – 适用于 Claude Desktop 的一键安装程序。

---

核心功能（按 README 所列）

类别	工具（部分）	功能
复习与学习	sync, get_due_cards, present_card, rate_card, forgetCards, setDueDate	与 AnkiWeb 同步、获取待复习卡片、显示卡片、记录评价或手动调整日程。
牌组管理	listDecks, deckStats, createDeck, changeDeck	列出牌组、获取详细统计、创建新牌组（支持两级层级）、在牌组间移动卡片。
笔记管理	addNote, addNotes, findNotes, notesInfo, updateNoteFields, deleteNotes	创建单个或批量笔记、使用 Anki 查询语法搜索、读取或编辑笔记字段、删除笔记。
标签管理	getTags, addTags, removeTags, replaceTags, clearUnusedTags	检索、添加、删除、重命名或清理标签。
媒体管理	getMediaFilesNames, retrieveMediaFile, storeMediaFile, deleteMediaFile	列出、下载（base64）、上传（路径、URL 或 base64）或删除媒体文件。README 建议使用文件路径或 URL 以提高速度。
模型/模板管理	modelNames, modelFieldNames, modelStyling, modelTemplates, createModel, updateModelStyling, addModelField …	检查、创建或修改笔记类型（模型）、字段、CSS 样式和卡片模板。
统计	collection_stats, review_stats	全局集合统计和复习历史分析。
GUI 工具（非复习）	guiBrowse, guiAddCards, guiEditNote, guiDeckOverview, guiCurrentCard, guiUndo	打开 Anki 桌面窗口或操作 UI 的命令，适用于交互式工作流。

服务器目前提供 53 个工具（42 个核心 + 11 个 GUI）。每个工具都通过 MCP JSON 协议调用，并返回 AI 可以解析和操作的结构化数据。

---

如何运行

1. 先决条件 – 安装 Anki、添加 AnkiConnect 插件，并需要 Node 22.12+。
2. 安装选项
   • npm（全局或 npx） – 运行 npm install -g @ankimcp/anki-mcp-server 然后运行 ankimcp，或使用 npx @ankimcp/anki-mcp-server 临时运行。
   • MCPB 捆绑包 – 从 GitHub Releases 页面下载 .mcpb 文件，并在 Claude Desktop 中安装（拖放或通过设置 → 扩展）。
   • 从源码 – 克隆、npm install、npm run build。
3. 选择传输方式
   • STDIO – 最适合桌面 AI 客户端。客户端将服务器作为子进程启动（ankimcp --stdio）。提供了 Claude Desktop、Cursor、Cline、Zed 和 opencode 的配置片段。
   • HTTP – 运行本地 Web 服务器（ankimcp 默认为 localhost:3000）。适用于基于 Web 的 AI 工具。
4. 远程访问（如果 AI 在云端运行）
   • 隧道（推荐） – ankimcp --tunnel 连接到托管 WebSocket 隧道服务，通过 OAuth 设备流进行身份验证，并为您提供可以提供给 ChatGPT、Claude.ai 等的公共 URL。
   • ngrok – 替代的、未认证的选项（README 中未详细说明）。

---

典型用例流程（来自 README 示例）

1. 复习牌组 – AI 发送 sync，然后发送 get_due_cards（可能按牌组过滤），使用 present_card 遍历返回的卡片，并在每个答案后调用 rate_card。
2. 创建新卡片 – AI 调用 modelNames 选择笔记类型，可选地为 RTL 阿拉伯语调用 createModel，然后使用所需字段调用 addNotes。
3. 添加图片 – AI 通过 storeMediaFile 上传本地文件，使用 guiSelectedNotes + notesInfo 获取当前选中的笔记，并使用 updateNoteFields 更新前字段以嵌入 <img> 标签。

---

谁可能受益？

• 希望获得可以随时获取、解释和编辑闪卡的对话式导师的学习者。
• 构建需要编程访问个人 Anki 集合的自定义 AI 代理的开发人员。
• 希望通过 LLM 驱动的脚本自动化批量笔记创建或媒体管理的教育工作者。

---

限制与注意事项（按 README）

• 服务器需要 AnkiConnect – 它不直接与 Anki 通信。
• 某些工具（例如 forgetCards、setDueDate）修改日程而不记录复习，这可能会影响长期统计。
• 远程访问需要托管隧道（推荐）或单独的隧道解决方案；不鼓励将 Anki 直接暴露到互联网。
• 对于大多数用户，AnkiMCP 插件更简单；此仓库主要用于需要 STDIO 或 MCPB 捆绑包的用户。

---

快速入门（通过 npx 使用 STDIO）

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

将上述 JSON 放入 AI 客户端的适当配置文件中（例如，Cursor 的 ~/.cursor/mcp.json），客户端将自动启动服务器。

---

总之： Anki MCP 服务器是一个基于 Node 的桥梁，让现代 LLM 驱动的助手可以通过定义良好的协议读取、编辑和管理您的 Anki 闪卡，支持本地 STDIO 和远程 HTTP/隧道连接。