Anki MCP

Anki MCP 服务器

测试版 - 本项目正在积极开发中。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 - 对卡片表现进行评分（重来、困难、良好、简单）并安排下次复习
• 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 - 极其缓慢且令牌效率低下

只需告诉 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 中的最后一个操作

前提条件

• 安装了 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 服务器的最简单方法：

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，本地基于 Web 的工具使用 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（本地基于 Web 的 AI）

HTTP 模式将服务器作为本地 Web 服务器运行，使用 MCP Streamable HTTP 协议。这是基于 Web 的 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

要使本地 HTTP 服务器可被云托管的 AI 访问，请使用下面的 远程 选项之一。

远程

托管/远程 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，因此它不如 隧道 安全。除非您有特定原因要管理自己的 ngrok 端点，否则请优先使用隧道。（需要全局安装 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_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 头值（逗号分隔的主机名）。绑定到 LAN/公共地址或在反向代理后运行时必需。请参阅 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" - 带有“重要”标签的笔记
• "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" - 来自任一牌组的笔记

重要说明

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 客户端和基于 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）

安全性：

• 主机头验证（DNS 重绑定保护） — 每个 HTTP 请求必须携带与允许列表匹配的 Host 头。默认情况下，仅接受回环主机（localhost、127.0.0.1、::1），无论端口如何。Host 是浏览器禁止的头，因此恶意网页无法伪造它——这关闭了 DNS 重绑定 路径，即重绑定的页面以伪造的 Host 且没有 Origin 到达服务器。不允许的 Host 将以 403 被拒绝。
• Origin 头验证 — 带有存在但不允许的 Origin/Referer 的浏览器请求将被拒绝。没有 Origin 的请求（curl、Postman、MCP-over-HTTP 客户端）被允许；主机验证是防止重绑定的防御措施。
• 默认绑定到 localhost (127.0.0.1)。
• 当前版本无身份验证（计划支持 OAuth）。

将 HTTP 模式暴露到 localhost 之外 — 如果您绑定到局域网/公共地址，或将服务器放在反向代理或公共域名后面，您必须设置 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 中记录日志

作为 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 模式（流式 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. 转到 运行 → 编辑配置
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. 选择 附加到 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              # 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 - 测试版/开发版（当前阶段）

  • 0.1.x - 错误修复和补丁
  • 0.2.0+ - 新功能或小改进
  • 破坏性更改在 0.x 版本中是可接受的

• 1.0.0 - 第一个稳定版本

  • 当 API 稳定并经过测试后发布
  • 破坏性更改将需要主版本号递增（2.0.0 等）

当前状态：0.22.0 - 活跃的测试版开发。最近的功能包括全集合复习分析（当省略 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 集成打下坚实基础，或计划大幅扩展功能，本项目的架构方法使其更易于长期维护和扩展。

有用链接

• Model Context Protocol 文档
• AnkiConnect API 文档
• Claude Desktop 下载
• 构建桌面扩展（Anthropic 博客）
• MCP 服务器仓库
• NestJS 文档
• 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 技术的独立项目。所有商标、服务标志、商号、产品名称和标志均归其各自所有者所有。