Anki MCP Server

Name: Anki MCP Server
Author: ankimcp.ai

本地服务

ankimcp.ai科研与教育5372 周前更新

代码仓库访问官网

关于 Anki MCP Server

Anki MCP Server让AI助手通过AnkiConnect读写Anki记忆卡片，涵盖复习、笔记、媒体、牌组和模板管理。适用于希望通过自然语言学习和整理卡片的用户，并支持STDIO传输。

主要功能

01复习卡片并记录评分
02批量创建和编辑笔记
03管理牌组、标签与媒体文件
04管理笔记类型、模板与CSS
05查询牌组统计与复习历史

适用场景

01让AI助手陪同复习外语牌组
02批量创建带RTL样式的词汇卡片
03从本地路径导入图片到笔记字段

MCP 相关

该项目是MCP服务器，向MCP客户端暴露53个工具，包括sync、get_due_cards、rate_card、addNotes和storeMediaFile等，通过STDIO或其他传输方式供Claude Desktop等客户端调用。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "ai-ankimcp-anki": {
      "command": "npx",
      "args": [
        "-y",
        "@ankimcp/anki-mcp-server"
      ]
    }
  }
}

启动命令npx -y @ankimcp/anki-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@ankimcp/anki-mcp-server0.27.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Anki MCP Server

通过 Model Context Protocol，将 Anki 与 AI 助手无缝集成

重要

对于大多数配置，建议使用 AnkiMCP 插件。

该插件（GitHub）可直接在 Anki 内运行 MCP 服务。无需安装 Node.js，无需配置 AnkiConnect，也无需保持单独的进程运行：使用代码 124672614 安装并重启 Anki 后，每次打开 Anki，服务都会启动。它支持本地 HTTP 访问，以及通过内置隧道进行远程访问。

如果你有以下特定需求，本仓库是合适的选择：

STDIO 传输 — Claude Desktop、Claude Code、Cursor，或任何会将服务作为子进程启动的客户端

MCPB 捆绑包 — 在 Claude Desktop 中一键安装 .mcpb

对于 HTTP、隧道或基于 Web 的客户端（claude.ai、ChatGPT），插件是更简单且支持更完善的方案。

本仓库不会被弃用。作为同一个 ankimcp.ai 项目的一部分，它将与插件一同维护和发布。

一个 Model Context Protocol（MCP）服务，可让 AI 助手与 Anki 这款间隔重复记忆闪卡应用进行交互。

通过自然语言交互，焕新你的 Anki 使用体验，就像拥有一位私人导师。AI 助手不仅会展示问题和答案，还能解释概念，让学习过程更生动、更贴近真人，提供背景信息，并适应你的学习方式。它可以随时创建和编辑笔记，让学习时段变成动态对话。更多功能即将推出！

示例和教程

如需了解将此 MCP 服务与 Claude Desktop 配合使用的完整指南、实际示例和分步教程，请访问：

ankimcp.ai — 提供实用示例和使用场景的完整文档

另请参阅 docs/ 中的补充文档，包括复习者设置指南和 Anki 示例牌组。

示例使用场景

以下是三个具有代表性的提示词，展示了此服务支持的工具调用流程：

“帮我复习西班牙语牌组。” — 助手会提议与 AnkiWeb 同步（sync），获取到期卡片（使用牌组筛选条件调用 get_due_cards），逐张展示卡片（present_card），并记录你的评分（rate_card）。由此展开自然的学习对话，并提供适合你的讲解。
“创建 10 张带 RTL 样式的阿拉伯语词汇卡片。” — 助手会列出笔记类型（modelNames），必要时创建自定义 RTL 笔记类型（使用 createModel + updateModelStyling 设置从右到左的 CSS），然后批量创建卡片（addNotes）。
“将 Downloads 文件夹中的这张图片导入所选笔记的正面。” — 助手会上传本地文件（通过文件路径调用 storeMediaFile），从浏览器读取当前选中的笔记（guiSelectedNotes + notesInfo），然后使用 <img> 标签更新正面字段（updateNoteFields）。

可用工具

该服务提供 53 个 MCP 工具 — 其中 42 个是日常 Anki 操作所需的基本工具，另有 11 个 GUI 工具，可操作 Anki 桌面界面来完成笔记编辑或创建工作流。

基本工具

复习与学习

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!"），但不记录复习
areSuspended - 检查一张或多张卡片的暂停状态，不做任何更改
suspend - 暂停卡片，使其在恢复暂停前跳过复习
unsuspend - 恢复卡片的暂停状态，使其回到正常复习

注意： 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 - 获取笔记的详细信息（字段、标签、笔记类型、卡片 ID；CSS 来自 modelStyling）
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 - 重命名现有笔记类型中的字段（Anki 会在卡片模板中重写对旧名称的引用）
repositionModelField - 更改现有笔记类型中字段的位置

统计信息

collection_stats - 所有牌组的汇总统计信息，包含各牌组明细和整个集合的卡片状态计数
review_stats - 复习历史分析（时间模式、记忆保留指标、学习连续记录）

GUI 工具

用于操控 Anki 桌面界面的工具。适用于笔记编辑／创建和牌组管理工作流，不适用于复习环节。

guiBrowse - 打开卡片浏览器并搜索卡片
guiSelectCard - 在卡片浏览器中选择特定卡片
guiSelectedNotes - 获取当前在卡片浏览器中选中的笔记 ID
guiAddCards - 打开添加卡片对话框并预填笔记详情
guiEditNote - 打开特定笔记的编辑器
guiDeckOverview - 打开特定牌组的概览对话框
guiDeckBrowser - 打开牌组浏览器对话框
guiCurrentCard - 获取复习模式下当前卡片的信息（包含答案；在复习模式之外会报错）
guiShowQuestion - 显示当前卡片的问题面
guiShowAnswer - 显示当前卡片的答案面
guiUndo - 撤销 Anki 中的上一个操作

前提条件

安装了 AnkiConnect 插件的 Anki
Node.js 22.12.0+

安装

有几种方式可以将服务安装到你的计算机上。安装完成后，前往连接 AI 客户端，将其接入你的 AI 助手——无论是本地还是远程。

npm（全局安装或 npx）

通用的服务安装方式，适用于任何直接启动该服务的 MCP 客户端。

对于运行 ankimcp 命令的客户端，请进行全局安装：

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

或者按需运行，无需安装：

npx @ankimcp/anki-mcp-server

MCPB 捆绑包（推荐用于 Claude Desktop）

为 Claude Desktop 安装此 MCP 服务的最简单方法：

从 Releases 页面下载最新的 .mcpb 捆绑包
在 Claude Desktop 中安装扩展：
- 方法 1：前往 Settings → Extensions，然后拖放 .mcpb 文件
- 方法 2：前往 Settings → Developer → Extensions → Install Extension，然后选择 .mcpb 文件
如有需要，配置 AnkiConnect URL（默认为 http://localhost:8765）
重启 Claude Desktop

就这么简单！该捆绑包包含在本地运行服务所需的一切。

致 Anthropic MCP Directory 审核人员： 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，本地 Web 工具使用 HTTP。
远程 —— 托管的/远程 AI（例如云端的 ChatGPT 或 Claude.ai）需要连接到你本地机器上运行的 Anki。使用托管的 Tunnel（✅ 推荐——经过身份验证），或使用更轻量、未经身份验证的替代方案 ngrok。

本地

服务运行在与 AI 客户端相同的计算机上，并通过 localhost 与 AnkiConnect 通信。

STDIO（主要的本地集成方式）

STDIO 是本地桌面 MCP 客户端的标准传输方式——Claude Desktop、Cursor IDE、Cline、Zed Editor、opencode 等。客户端会将服务作为子进程启动，并通过标准输入/输出进行通信。

支持的客户端：

Claude Desktop
Cursor IDE - AI 驱动的代码编辑器
Cline - 用于 AI 辅助的 VS Code 扩展
Zed Editor - 快速、现代的代码编辑器
opencode - 终端 AI 编码 Agent
其他支持 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"
      }
    }
  }
}

opencode 使用自己的格式——服务器配置在 mcp 下，命令是一个数组，环境变量配置在 environment 下：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "anki-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "enabled": true,
      "environment": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

配置文件位置：

Cursor IDE：~/.cursor/mcp.json（macOS/Linux）或 %USERPROFILE%\.cursor\mcp.json（Windows）
Cline：可通过 VS Code 中的设置界面访问
Zed Editor：通过扩展市场将其安装为 MCP 扩展
opencode：项目根目录中的 opencode.json，或全局位置 ~/.config/opencode/opencode.json

有关客户端特定功能和故障排除，请参阅 MCP 客户端的文档。另请参阅连接到 Claude Desktop，了解直接指向已构建的 dist/main-stdio.js 的配置。

HTTP（本地 Web AI）

HTTP 模式会将服务作为本地 Web 服务运行，并使用 MCP Streamable HTTP 协议。这是基于 Web 的 AI 工具指向你的机器时与之通信的传输方式，也是远程选项向外部开放的内容。HTTP 模式本身只绑定到 localhost。

需要绑定到 localhost 以外的地址？ 如果传入 --host 0.0.0.0（或在反向代理／公共域名后运行），出于 DNS 重绑定防护，服务默认只接受 Host 标头为回环地址的请求——请将客户端使用的主机名设置到 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 的人开放。

隧道模式让基于 Web 的 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 content changes and rescheduling; rating, suspend and sync still work)
  --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 标志（或 READ_ONLY=true）会阻止修改笔记内容、牌组、标签、媒体和笔记类型，以及手动调整卡片的复习时间。启用后：

所有读取操作均可正常使用（浏览牌组、查看卡片、搜索笔记）
仍允许以下操作：复习时为卡片评分（rate_card）、暂停／取消暂停卡片（suspend、unsuspend）、与 AnkiWeb 同步（sync），以及用于导航 Anki 窗口的 GUI 工具（guiBrowse、guiDeckOverview，……）
会阻止修改内容（addNote、deleteNotes、createDeck、updateNoteFields 等）；如果牌组已存在，createDeck 仍会成功，因为不会写入任何内容
会阻止手动调整复习时间：forgetCards（重置为新卡片）和 setDueDate
会阻止 guiUndo，因为撤销操作可能会还原对集合的更改
会阻止 guiAddCards 和 guiEditNote，因为在这些工具打开的对话框中添加或保存笔记会写入集合
适用于探索 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 中配置服务端：

前往：Settings → Developer → Edit Config
或手动编辑配置文件

配置

将以下内容添加到 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_URL`	AnkiConnect URL	`http://localhost:8765`
`ANKI_CONNECT_API_VERSION`	API 版本	`6`
`ANKI_CONNECT_API_KEY`	如果在 AnkiConnect 中配置，则使用 API 密钥	-
`ANKI_CONNECT_TIMEOUT`	请求超时时间，单位为毫秒	`5000`
`READ_ONLY`	启用只读模式（`true` 或 `1`）	`false`
`PORT`	HTTP 模式：监听端口（`--port` 标志优先）	`3000`
`HOST`	HTTP 模式：绑定地址（`--host` 标志优先）	`127.0.0.1`
`ALLOWED_HOSTS`	HTTP 模式：除环回地址外允许接受的额外 `Host` 标头值（以逗号分隔的主机名）。绑定到局域网或公共地址，或在反向代理后运行时必须设置。参见 HTTP 模式配置。	仅环回地址
`ALLOWED_ORIGINS`	HTTP 模式：允许的浏览器 `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" - Spanish 牌组中带有 verb 标签的笔记（AND）
"deck:Spanish OR deck:French" - 来自 Spanish 或 French 牌组的笔记

重要说明

CSS 和 HTML 处理

notesInfo 工具会返回每条笔记的笔记类型名称；CSS 本身由 modelStyling 提供
updateNoteFields 工具支持字段中的 HTML 内容，并会保留 CSS 样式
每个笔记模型都有自己的 CSS 样式；使用 modelStyling 获取特定模型的 CSS

更新警告

⚠️ 重要：使用 updateNoteFields 时，请勿在更新期间通过 Anki 浏览器查看笔记，否则字段将无法正确更新。更新前请关闭浏览器或切换到其他笔记。更多详情请参见已知问题。

删除安全性

deleteNotes 工具要求明确确认（confirmDeletion: true），以防止意外删除。删除笔记会永久移除所有关联卡片。

安全

媒体文件路径和 URL 验证

媒体工具（storeMediaFile、retrieveMediaFile、deleteMediaFile）以及 updateNoteFields 的音频／图片字段包含安全验证，以防止通过提示词注入滥用：

文件路径导入仅限媒体文件类型（图像、音频、视频）。系统会根据 MIME 类型拒绝非媒体文件（例如 SSH 密钥、凭据、Shell 配置）。配置 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 之间进行，不属于此服务的范围。
保留期限：不适用——服务端不会保留数据。
联系方式：[email protected]

已知问题

如需了解已知问题和限制的完整列表，请访问我们的文档：

已知问题文档

关键限制

在浏览器中查看笔记时，笔记更新会失败

⚠️ 重要：使用 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 客户端和基于 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/（根路径）

隧道模式（托管 WebSocket 隧道）

适用于通过托管的 AnkiMCP 隧道服务接入的基于 Web 的 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，仅限本地主机）
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 验证是防范重绑定的措施。
默认绑定到本地主机（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

如果绑定到 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

此命令将：

将 package.json 中的版本同步到 manifest.json
移除旧的 .mcpb 文件
构建 TypeScript 项目
将 dist/ 和 node_modules/ 打包到 .mcpb 文件中
运行 mcpb clean 以移除 devDependencies（将捆绑包从约 47MB 优化至约 10MB）

输出文件名为 anki-mcp-server-X.X.X.mcpb，可用于一键安装和分发。

捆绑包包含的内容

MCPB 捆绑包包含：

编译后的 JavaScript（dist/ 目录 - 包含全部三个入口点）
仅包含生产依赖（node_modules/ - mcpb clean 会移除 devDependencies）
软件包元数据（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 模式（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

前往 Run → Edit Configurations
添加新的 Attach to Node.js/Chrome 配置
将端口设为 9229
点击 Debug 进行附加

VS Code

打开调试面板（Ctrl+Shift+D / Cmd+Shift+D）
选择 Debug MCP Server (Attach) 配置
按 F5 进行附加

步骤 4：设置断点并调试

附加后，你可以：

在 TypeScript 源文件中设置断点
单步执行代码
检查变量和调用堆栈
使用调试控制台计算表达式

调试器会使用源映射，让你调试原始 TypeScript 代码，而不是编译后的 JavaScript。

在 Claude Desktop 中调试

你也可以启用 Node.js 调试器并附加 IDE，在 Claude Desktop 内运行 MCP 服务时进行调试。

步骤 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

前往 Run → Edit Configurations
点击 + 按钮并选择 Attach to Node.js/Chrome
配置：
- Name：Attach to Anki MCP (Claude Desktop)
- Host：localhost
- Port：9229
- Attach to：Node.js < 8 或 Chrome or Node.js > 6.3（视 WebStorm 版本而定）
点击 OK
点击 Debug（Shift+F9）进行附加

VS Code

将以下内容添加到 .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"]
    }
  ]
}

打开调试面板（Ctrl+Shift+D / Cmd+Shift+D）
选择 Attach to Anki MCP (Claude Desktop)
按 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 会创建一个 .tgz 文件，其内容与运行 npm publish 创建的文件完全相同
从 .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 - Bug 修复和补丁
- 0.2.0+ - 新功能或小幅改进
- 0.x 版本允许包含破坏性变更
1.0.0 - 首个稳定版本
- 将在 API 稳定并经过测试后发布
- 破坏性变更将需要提升主版本号（2.0.0 等）

当前状态：0.27.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。

第三方归属声明

Anki® 是 Ankitects Pty Ltd. 的注册商标。本项目是非官方的第三方工具，与 Ankitects Pty Ltd. 无关联，未经其认可，也未得到其赞助。Anki 徽标依据替代许可证使用，用于指向 https://apps.ankiweb.net 的链接。有关 Anki 官方应用，请访问 https://apps.ankiweb.net。
Model Context Protocol（MCP） 是 Anthropic 制定的开放标准。MCP 徽标来自官方 MCP 文档仓库，依据 MIT 许可证使用。有关 MCP 的更多信息，请访问 https://modelcontextprotocol.io。
这是一个连接 Anki 与 MCP 技术的独立项目。所有商标、服务标记、商号、产品名称和徽标均归各自所有者所有。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。