AnkiMCP Server

AnkiMCP Server（插件）

Anki 插件，可通过 Model Context Protocol (MCP) 向 AI 助手开放你的卡片集合。

这是什么？

AnkiMCP Server 会在 Anki 中运行本地 MCP 服务，让 Claude 等 AI 助手能够与你的闪卡集合互动。借此可以开展 AI 驱动的学习、创建卡片和管理卡片集合。

这是 ankimcp.ai 项目的一部分。

首次运行说明

首次运行时，此插件会从 PyPI 下载 pydantic_core（约 2MB）。这是必需的，因为 pydantic_core 包含特定于平台的二进制文件（Windows/macOS/Linux），无法将其打包到单个插件文件中。

第二个原生依赖项 rpds（来自 rpds-py）也采用相同的处理方式，但几乎不会下载：Anki 已将 rpds 作为其自身 jsonschema 的传递依赖一同提供，因此插件只需导入它。只有在极少数导入失败的安装中，才会触发下载。两个依赖项都会缓存在 Anki 自身的数据文件夹中（位于插件文件夹之外，因此在所有操作系统上更新插件后都能妥善保留）；如果该位置不可用，则会回退到插件的 _cache/ 目录。因此，无论哪种情况，它们都只会下载一次，而不是每次启动时都下载。只有在外部缓存确认可用（成功从中加载）后，才会移除旧的插件文件夹内回退缓存；只要仍有原生模块从该缓存加载，就绝不会动它——首次尝试失败（例如处于离线状态）时，会保留旧缓存，不会将其删除。

功能

• 本地 HTTP 服务 - 默认运行在 http://127.0.0.1:3141/
• 远程隧道 - 通过公开的 HTTPS URL 从任何地方访问你的卡片集
• MCP 协议 - 兼容任何 MCP 客户端（Claude Desktop 等）
• 自动启动 - Anki 打开时 HTTP 服务会自动启动
• 支持隧道 - 可与 Cloudflare Tunnel、ngrok 或内置隧道配合使用（通过这种方式暴露 HTTP 服务还需要扩展允许的主机/来源）
• DNS 重绑定防护 - 默认情况下，HTTP 服务会根据回环地址许可名单验证 Host/Origin 标头；如需通过隧道/反向代理暴露服务，请扩展许可名单
• 可选 API 密钥 - 通过 http_api_key 要求 HTTP 传输提供 Authorization: Bearer 令牌（类似 AnkiConnect；留空 = 禁用）
• 工具栏指示器 - 顶部工具栏中的 ● AnkiMCP 项目会一目了然地显示隧道连接状态（可通过 show_toolbar_indicator 选择不显示）
• 诊断日志 - 启用 log_to_file 后，会将轮换且已隐藏机密信息的日志写入 user_files/ankimcp.log，设置中还提供 Open log folder / Copy diagnostics 按钮
• 字段管理 - 通过 model_field_* 工具添加、重命名和调整笔记类型字段的位置（可选择启用破坏性工具 model_field_remove）
• 批量卡片统计 - 只读工具 cards_stats 可返回整个牌组（包括子牌组）中每张卡片的精简调度指标（类型/队列/间隔/标签/dueToday），不依赖 FSRS——适用于分析的轻量级批量读取
• GUI 复习会话 - 在 Anki 自带的复习器窗口中免提复习：gui_deck_review 打开牌组，gui_answer_card 为你按下答题按钮。选择启用，只有在 enabled_opt_in_tools 中指定后才会显示
• MCP 工具注释 - 每个工具都会声明 title、readOnlyHint、destructiveHint 和 openWorldHint（以及可安全重复执行的写入工具的 idempotentHint），以便客户端显示易读名称，并在更改数据前进行确认
• 跨平台 - 支持 macOS、Windows 和 Linux（x64 和 ARM）

安装

从 AnkiWeb 安装（推荐）

1. 打开 Anki，前往 Tools → Add-ons → Get Add-ons...
2. 输入代码：124672614
3. 重启 Anki

从 GitHub Releases 安装

1. 从 Releases 下载 anki_mcp_server.ankiaddon
2. 双击安装，或使用 Tools → Add-ons → Install from file...
3. 重启 Anki

NixOS

使用 flakes（推荐）

添加 flake 输入并使用预构建的软件包：

# flake.nix
{
  inputs.anki-mcp.url = "github:ankimcp/anki-mcp-server-addon";

  outputs = { nixpkgs, anki-mcp, ... }: {
    # Option A: Standalone — Anki with the addon pre-installed
    environment.systemPackages = [
      anki-mcp.packages.${system}.default
    ];

    # Option B: Composable with other addons via overlay
    nixpkgs.overlays = [ anki-mcp.overlays.default ];
    environment.systemPackages = [
      (pkgs.anki.withAddons [ pkgs.ankiAddons.anki-mcp-server ])
    ];
  };
}

不使用 flakes

# configuration.nix
{ pkgs, ... }:
let
  python3 = pkgs.python3;

  ankiMcpPythonDeps = python3.withPackages (ps: with ps; [
    mcp pydantic pydantic-settings starlette uvicorn anyio httpx websockets
  ]);

  anki-mcp-server = pkgs.anki-utils.buildAnkiAddon (finalAttrs: {
    pname = "anki-mcp-server";
    version = "0.20.0";
    src = pkgs.fetchFromGitHub {
      owner = "ankimcp";
      repo = "anki-mcp-server-addon";
      rev = "v${finalAttrs.version}";
      hash = ""; # nix will tell you the correct hash on first build
    };
    sourceRoot = "${finalAttrs.src.name}/anki_mcp_server";
  });

  ankiWithMcp = pkgs.anki.withAddons [ anki-mcp-server ];

  ankiWrapped = pkgs.symlinkJoin {
    name = "anki-with-mcp";
    paths = [ ankiWithMcp ];
    nativeBuildInputs = [ pkgs.makeWrapper ];
    postBuild = ''
      wrapProgram $out/bin/anki \
        --prefix PYTHONPATH ':' "${ankiMcpPythonDeps}/${python3.sitePackages}"
    '';
  };
in
{
  environment.systemPackages = [ ankiWrapped ];
}

使用

打开 Anki 时，服务会自动启动。通过 Tools → AnkiMCP Server Settings... 查看状态。

连接 Claude Desktop

需要安装 Node.js。将以下内容添加到 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3141"]
    }
  }
}

注意： Claude Desktop 的 JSON 配置原生不支持 HTTP 服务——mcp-remote 会通过 stdio 转接连接。

连接 Claude Code

claude mcp add anki --transport http http://127.0.0.1:3141/

Opencode

opencode mcp add anki --url http://127.0.0.1:3141/

隧道（远程访问）

内置隧道会为你的 Anki collection 提供一个公开的 HTTPS URL，让 AI 助手可以随时随地访问，无需配置端口转发或反向代理。collection 会通过 WebSocket 隧道服务（默认：wss://tunnel.ankimcp.ai）进行中继。需要使用 ankimcp.ai 账号登录。

连接方法：

1. 打开 Tools -> AnkiMCP Server Settings...
2. 点击 Connect Tunnel
3. 如果尚未登录，会出现登录对话框，其中会显示一次性代码；点击 Open Browser，然后在验证 URL 中输入该代码（OAuth 2.0 设备授权流程）
4. 连接后会显示一个公开的隧道 URL（例如，https://tunnel.ankimcp.ai/e3439277-9d1e-47a1-b961-d193a4590da0）
5. 在 AI 客户端中使用此 URL 替代 http://127.0.0.1:3141

在 Claude Desktop 中使用：

在 Claude Desktop 配置中，将 localhost URL 替换为隧道 URL：

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["mcp-remote", "https://tunnel.ankimcp.ai/<your-tunnel-id>"]
    }
  }
}

在 Claude Code 中使用：

claude mcp add anki --transport http https://tunnel.ankimcp.ai/<your-tunnel-id>

断开连接与退出登录：

• 断开连接会关闭隧道连接。凭据会保留在磁盘上；下次连接时会自动重连，无需重新登录。
• 退出登录会删除凭据。下次连接时会再次触发登录对话框。

隧道配置字段（适用于高级用户 / 可自托管用户）：

• tunnel_server_url — 隧道中继服务的 WebSocket URL（默认：wss://tunnel.ankimcp.ai）
• tunnel_client_id — OAuth 客户端标识符（默认：ankimcp-cli）

凭据存储在插件自己的 user_files/credentials.json 中（插件更新后仍会保留）。这些凭据不会与 AnkiMCP CLI 共享 — CLI 会将自己的凭据保存在 ~/.ankimcp/ 下，因此你需要分别登录插件和 CLI。两者的磁盘存储格式相同。

配置

通过 Anki 的 Tools → Add-ons → AnkiMCP Server → Config 进行编辑：

{
  "http_enabled": true,
  "http_port": 3141,
  "http_host": "127.0.0.1",
  "http_path": "",
  "http_allowed_hosts": [],
  "http_allowed_origins": [],
  "http_api_key": "",
  "cors_origins": [],
  "cors_expose_headers": ["mcp-protocol-version"],
  "disabled_tools": [],
  "enabled_destructive_tools": [],
  "enabled_opt_in_tools": [],
  "max_notes_per_batch": 100,
  "tunnel_server_url": "wss://tunnel.ankimcp.ai",
  "tunnel_client_id": "ankimcp-cli",
  "media_import_dir": "",
  "media_allowed_types": [],
  "media_allowed_hosts": [],
  "show_settings_menu_item": true,
  "show_toolbar_indicator": true,
  "show_sync_tooltip": true,
  "log_to_file": false
}

HTTP 服务开关

http_enabled 设置用于控制本地 HTTP 服务是否运行。设为 false 时，HTTP 服务不会启动 — 仅提供隧道传输。默认值为 true。

{
  "http_enabled": false
}

如果你只使用隧道，不希望本地 HTTP 服务处于监听状态，这项设置就很有用。

工具菜单项

默认情况下，Anki 的 Tools 菜单中会显示 AnkiMCP Server Settings… 条目。将 show_settings_menu_item 设为 false 可将其隐藏（Anki 重启后生效）。

{
  "show_settings_menu_item": false
}

注意：如果你同时隐藏菜单项和工具栏指示器，应用内就没有其他方式可以打开设置对话框 — 你仍可通过 Tools → Add-ons → AnkiMCP Server → Config 编辑配置。

工具栏状态指示器

Anki 顶部工具栏中会持续显示 ● AnkiMCP 项，用于显示隧道连接状态（灰色 = 关闭，琥珀色 = 正在连接，绿色 = 已连接）；点击该项可打开设置对话框。默认显示。将 show_toolbar_indicator 设为 false 可将其隐藏（Anki 重启后生效）。

{
  "show_toolbar_indicator": false
}

同步提示

AI 客户端触发同步时，插件会在 Anki 界面中显示简短的非模态提示，分别在同步开始和完成时出现（例如 AnkiMCP: syncing…、AnkiMCP: sync complete）。这是这些原本不会显示提示的后台同步唯一的视觉提示。默认显示。将 show_sync_tooltip 设为 false 可将其关闭。

{
  "show_sync_tooltip": false
}

诊断日志文件

将 log_to_file 设置为 true，即可在 user_files/ankimcp.log 中写入轮转日志（每个文件约 1 MB，保留 3 个备份）。此功能默认关闭。启用后，插件会记录启动诊断快照（插件、Anki、Qt、Python 版本，以及 pydantic、mcp、protobuf 等共享库的实时来源信息），这是诊断插件间冲突的关键数据。任何写入磁盘前，都会对机密信息——http_api_key、OAuth 令牌和任何 Bearer 令牌——进行脱敏。

{
  "log_to_file": true
}

设置对话框（工具 → AnkiMCP Server Settings…）中有 打开日志文件夹 按钮和 复制诊断信息 按钮（相同的快照，格式适合粘贴到论坛帖子中）。重启 Anki 后生效。

禁用工具

隐藏特定工具，以减少 AI 客户端的令牌用量：

{
  "disabled_tools": [
    "sync",
    "card_bury",
    "card_unbury"
  ]
}

每个条目都是一个工具名称。禁用的工具会从 MCP 架构中彻底移除，AI 客户端完全看不到它们。工具名称拼写错误会在控制台中产生警告。

升级到 0.40.0

0.40.0 将四个多操作工具拆分为每个操作一个工具：card_management → card_*、tag_management → tag_*、filtered_deck → filtered_deck_*、model_fields → model_field_*（参见可用工具）。旧配置条目仍然有效，并会显示指出替代工具的弃用警告：

• "card_management:bury" 的行为与 "card_bury" 完全相同——适用于 disabled_tools 和下面两个允许列表（"model_fields:remove" 仍会启用 model_field_remove）
• 在 disabled_tools 中填写裸名称 "card_management" 会禁用所有 card_* 工具
• 在 enabled_destructive_tools / enabled_opt_in_tools 中填写裸旧名称不会启用任何工具，与之前一样

只有这些旧名称接受 "tool:action" 格式；任何其他 "tool:action" 条目都不会匹配任何工具，并会产生警告。每次打开配置文件时都会显示弃用警告（在服务器启动后显示，不会延迟服务器启动），直到你切换为新名称。

这些别名仅适用于配置。在客户端一侧，旧工具已移除：tools/list 不再包含 card_management 等工具，新工具使用扁平参数——没有 params 包装，也没有 action 字段。如果你的 AI 客户端保存了按工具设置的审批记录，或者脚本调用了旧工具，请重新审批新工具并更新调用代码。

破坏性工具（选择启用）

被归类为破坏性工具（高风险操作）的工具默认对 AI 客户端隐藏。如需开放这些工具，请将它们添加到 enabled_destructive_tools 允许列表中：

{
  "enabled_destructive_tools": [
    "change_note_type",
    "model_field_remove"
  ]
}

• 每个条目都必须是破坏性工具的精确名称
• disabled_tools 仍然优先适用——已选择启用的工具仍可被禁用
• 不匹配任何工具或匹配到非破坏性工具的条目会在控制台中产生警告

这是服务端强制执行的：在选择启用之前，破坏性工具不会出现在 MCP 架构中，因此即使客户端行为异常，也无法调用它们。目前提供的破坏性工具有：change_note_type（重写每个所选笔记的字段布局）和 model_field_remove（永久删除该笔记类型所有笔记中的一个字段及其内容）。

选择启用的工具

出于“破坏性”以外的原因（例如新的／实验性功能），某些工具默认对 AI 客户端隐藏。可通过 enabled_opt_in_tools 允许列表开放这些工具，语法与 enabled_destructive_tools 相同：

{
  "enabled_opt_in_tools": [
    "gui_answer_card",
    "gui_deck_review"
  ]
}

• 每个条目都必须是选择启用工具的精确名称
• disabled_tools 仍然优先适用——已选择启用的工具仍可被禁用
• 不匹配任何工具或匹配到非选择启用工具的条目会在控制台中产生警告

目前提供的选择启用条目有：gui_deck_review 和 gui_answer_card——用于 GUI 免手动操作复习会话的工具。

自定义路径

将 http_path 设置为通过自定义路径提供 MCP 端点。当通过隧道（Cloudflare、ngrok）公开 Anki，以避免端点完全开放时，此设置很有用：

{
  "http_path": "my-secret-path"
}

服务器将在 http://localhost:3141/my-secret-path/ 访问，而不是在根路径访问。留空则使用默认行为。

注意： 仅设置自定义路径不足以通过隧道或反向代理公开 HTTP 服务器。你还必须填写 http_allowed_hosts/http_allowed_origins，否则请求会被拒绝（非环回 Host 返回 421，非环回 Origin 返回 403）——请参阅允许的主机和来源（DNS 重绑定保护）。

安全性

默认情况下，本地 HTTP 服务器仅接受来自环回 Host/Origin 值的请求，因此普通本地使用无需任何设置——本地主机客户端开箱即用。以下部分介绍可用的安全强化措施（DNS 重绑定允许列表、可选 API 密钥、CORS 和媒体导入验证），适用于需要在本机以外公开服务器的情况。

**从 ≤ 0.20.0 升级：**如果你通过隧道、反向代理访问服务器，或绑定到 0.0.0.0，请求现在会携带非环回 Host，在允许列表中添加该主机之前会被 421 拒绝——请参阅允许的主机和来源（DNS 重绑定保护）。（浏览器客户端还需要将其 Origin 加入允许列表，否则会返回 403。）普通的本地主机配置不受影响。

允许的主机和来源（DNS 重绑定保护）

HTTP 服务器启用 DNS 重绑定保护，并内置环回允许列表（逐字复制自 MCP SDK 自身的默认值）：

• 主机：127.0.0.1:*、localhost:*、[::1]:*
• 来源：http://127.0.0.1:*、http://localhost:*、http://[::1]:*

因此，普通的本地主机客户端开箱即用。以下两点默认配置值得了解：

• :* 模式匹配带端口的主机（localhost:3141 ✓）。不带端口的 Host 标头（浏览器和客户端仅在服务器运行于端口 80 时才会发送）不匹配，因此非默认的 "http_port": 80 需要将 "localhost"/"127.0.0.1" 显式添加到 http_allowed_hosts。
• 默认来源仅支持 http://。https://localhost 来源不在覆盖范围内，必须添加到 http_allowed_origins。（完全没有 Origin 标头的请求——非浏览器 MCP 客户端的常见情况——始终会通过。）

如果你通过隧道或反向代理（例如 ngrok、Cloudflare）公开 HTTP 服务器，请求会携带非环回 Host（返回 421）——对于浏览器客户端，还会携带非环回 Origin（返回 403）——除非你扩展允许列表：

{
  "http_allowed_hosts": ["myapp.ngrok.io", "myapp.ngrok.io:443"],
  "http_allowed_origins": ["https://myapp.example"]
}

• http_allowed_hosts——不带方案的 Host 标头值（例如 "myapp.ngrok.io" 或 "myapp.ngrok.io:443"）
• http_allowed_origins——带方案的完整来源（例如 "https://myapp.example"）

这两个列表都会追加到内置的环回默认值中（不会替换默认值）。更改这些设置后需要重启 Anki，与其他 http_* 设置一致。

DNS 重绑定漏洞由 avishaigo-commits 报告。

API 密钥（可选 HTTP 身份验证）

http_api_key 会在 HTTP 传输之上添加一个可选的共享密钥身份验证层（类似 AnkiConnect）。它默认为空，因此会禁用此层，默认行为保持不变。设置为非空值后，每个 HTTP 请求都必须发送与该值匹配的 Authorization: Bearer <key> 标头，否则请求将被拒绝，并返回 403：

{
  "http_api_key": "a-long-random-secret-key"
}

配置客户端发送该标头。使用 Claude Code 时：

claude mcp add anki --transport http http://127.0.0.1:3141/ --header "Authorization: Bearer a-long-random-secret-key"

使用 mcp-remote 时（例如 Claude Desktop）：

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:3141",
        "--header",
        "Authorization: Bearer a-long-random-secret-key"
      ]
    }
  }
}

注意：

• 仅适用于 HTTP。 此密钥仅适用于本地 HTTP 传输。隧道会自行进行 OAuth 登录，不受 http_api_key 影响。
• 互为补充，而非替代。 它与 DNS 重绑定防护（Allowed Hosts 和 Origins）并行工作，不会取而代之。这两层各自独立生效。
• 通过隧道或反向代理公开 HTTP 服务时，http_path 和 http_allowed_hosts 搭配使用效果很好：秘密路径可隐藏端点，允许列表可放行代理主机，而 API 密钥则用于验证每个请求。
• 请使用较长的随机密钥（至少 16 个字符）。提交的令牌前后空白会被去除，因此配置的密钥如果带有前后空白，将永远无法匹配。
• 更改此设置需要重启 Anki，与其他 http_* 设置一致。

CORS 配置

若要允许基于浏览器的 MCP 客户端（例如托管在 Web 上的 MCP Inspector），请添加允许的来源：

{
  "cors_origins": ["https://inspector.example.com", "http://localhost:5173"]
}

使用 ["*"] 可允许所有来源（不建议用于生产环境）。

注意： 通过 cors_origins 允许的浏览器来源，也必须添加到 http_allowed_origins 中。CORS 和 DNS 重绑定允许列表是两个独立的层：即使已配置 CORS，非回环的 Origin 仍会被 DNS 重绑定防护拒绝，并返回 403，除非它已列入 http_allowed_origins。

cors_expose_headers 设置用于控制浏览器可以读取哪些响应标头。默认值（mcp-protocol-version）可让基于浏览器的 MCP 客户端协商协议版本。从 v0.16.0 开始，服务以无状态模式运行，因此不再发送 mcp-session-id，也无需再公开此标头。

媒体安全

感谢哥伦比亚大学的 Hideaki Takahashi 负责任地披露媒体路径遍历漏洞。

store_media_file 工具会验证所有输入，以防止路径遍历和 SSRF 攻击：

• 文件路径通过 MIME 类型检查限制为媒体文件（图像、音频、视频）
• URL 必须使用 http:// 或 https://，且不能指向私有或内部网络
• 文件名会经过清理，以移除路径遍历序列

可通过配置进行可选的加固：

{
  "media_import_dir": "/Users/me/anki-media",
  "media_allowed_types": ["application/pdf"],
  "media_allowed_hosts": ["192.168.1.50", "my-nas.local"]
}

• media_import_dir — 将文件路径导入限制在此目录树内（为空 = 不限制）
• media_allowed_types — 允许图像、音频和视频之外的其他 MIME 类型
• media_allowed_hosts — 允许指定主机绕过私有网络拦截

可用工具

每个工具参数在 MCP 输入架构中都带有简短的 description（自 0.29.0 起），因此展示或将该架构提供给模型的客户端无需反复试错即可了解参数结构。嵌套对象（例如 tag_batch 操作、filtered_deck_upsert 搜索词）在其 Pydantic 模型上进行了说明，并显示在 $defs 下。

每个工具还带有 MCP 注释（自 0.31.0 起）：便于人类阅读的 title、readOnlyHint（对于不会修改集合的工具为 true）、destructiveHint（对于只读工具以及可逆且不会丢失数据的写入操作为 false：add_note、add_notes、create_deck、create_model、store_media_file、tag_add、card_bury、card_unbury、card_suspend、card_unsuspend、card_set_flag、card_change_deck、filtered_deck_empty 和 filtered_deck_rebuild；对于其他所有写入工具均为 true，即会删除、覆盖或不可逆地更改数据，或强制执行完整 AnkiWeb 同步的工具）、idempotentHint（自 0.32.0 起；仅对于重复相同调用不会产生额外效果的写入工具为 true：create_deck、delete_notes、delete_media_file、set_fsrs_params、card_change_deck、card_bury、card_unbury、card_suspend、card_unsuspend、card_set_flag、所有 tag_* 写入工具、filtered_deck_empty、filtered_deck_delete 以及所有 model_field_* 写入工具；其他工具均不设置此注释），以及 openWorldHint（仅对于会与 AnkiWeb 通信的 sync 和可以获取 URL 的 store_media_file 为 true）。

从 ≤ 0.27.x 升级：get_due_cards 不再返回 back，除非传入 include_answer=true；现在 front 是渲染后的问题 HTML，而不是原始字段。读取此工具返回的 back 的客户端需要设置该标志。

基本工具

工具	描述
sync	与 AnkiWeb 同步集合（异步任务：sync() 启动同步，sync(job_id) 查询状态，sync(job_id, resolve=...) 解决完整同步冲突）
list_decks	列出集合中的所有牌组
create_deck	创建新牌组
find_notes	使用 Anki 搜索语法搜索笔记。include_first_field=true 会添加一个 noteLabels 数组（{noteId, firstField, truncated, fullLength}），让你可以在一次调用中搜索并标记笔记
notes_info	获取笔记的详细信息。excerpt_chars 将每个字段值限制为指定字符数，并为每个值标记 truncated/fullLength，便于快速浏览大量笔记
add_note	向牌组添加新笔记
add_notes	批量添加最多 max_notes_per_batch 条笔记（默认 100），这些笔记共用同一牌组和笔记类型。使用 Anki 原生批量 API，实现原子化撤销。支持部分成功，单条失败不会影响其他笔记
card_reposition	设置新卡片的学习顺序（仅影响新卡片）
card_change_deck	将卡片移至其他牌组；如有需要，会创建该牌组
card_bury / card_unbury	将卡片隐藏至明天 / 恢复牌组中所有已埋藏的卡片
card_suspend / card_unsuspend	无限期暂停卡片复习 / 恢复卡片
card_set_flag	设置或移除颜色标记（0-7）
card_set_due_date	使用天数 DSL（0、5、5-7、5!）重新安排卡片
card_forget	将卡片重置为新卡片
tag_add / tag_remove	批量为笔记添加/移除标签
tag_replace	将笔记的一个标签替换为另一个
tag_list	列出所有标签；也可通过可选参数 deck 限定牌组范围，列出牌组中有卡片的笔记上的不重复标签（包括子牌组）
tag_clear_unused	移除孤立标签
tag_batch	在一次调用中执行多个添加/移除标签操作，支持部分成功
filtered_deck_upsert	根据 1-2 个搜索词创建或修改筛选牌组（Anki 的硬性上限）
filtered_deck_rebuild	重新填充筛选牌组
filtered_deck_empty	将筛选牌组中的卡片移回所属牌组
filtered_deck_delete	将筛选牌组中的卡片移回所属牌组，然后删除该牌组
filtered_deck_get_info	每次调用只读检查最多 50 个牌组 ID，返回搜索词、上限、顺序、重新安排时间表标记和卡片数量；非筛选牌组会返回 is_filtered=false，未知 ID 会被跳过并计入 not_found
update_note_fields	更新现有笔记的字段。支持两种模式：完整替换，或通过 old_str/new_str 进行补丁（在字段内查找并替换；必须恰好匹配一次，否则不会写入任何内容）
update_notes	在一个原子化撤销步骤中批量更新多条笔记的字段（单次后端调用）。先验证每个条目；最多支持 max_notes_per_batch 条笔记，且支持部分成功
delete_notes	从集合中删除笔记
get_due_cards	获取下一张待复习卡片（语音模式支持 skip_images/skip_audio）。仅返回渲染后的正面内容；除非 include_answer=true，否则不包含答案
cards_stats	获取牌组（包括子牌组）中每张卡片的批量排程统计信息：类型/队列/间隔/标签/dueToday，支持分页。与 FSRS 无关，数据载荷精简，适用于分析
present_card	获取用于复习的卡片内容
rate_card	复习后为卡片评分（Again/Hard/Good/Easy）
model_names	列出可用的笔记类型
model_field_names	获取笔记类型的字段名称和描述
model_styling	获取笔记类型的 CSS 样式。include_latex=true 还会返回 LaTeX 导言（latex_pre、latex_post、latex_svg）
update_model_styling	更新笔记类型的 CSS 样式：完整替换，或通过 old_str/new_str 进行补丁（必须恰好匹配一次）。也可写入 LaTeX 导言（latex_pre/latex_post/latex_svg）
model_templates	读取笔记类型中每种卡片类型的正面/背面 HTML 模板
update_model_templates	更新正面/背面模板 HTML：完整替换，或通过 old_str/new_str 进行补丁（必须恰好匹配一次）。会提前拒绝无法识别的键（区分大小写）和未知模板名称，并以原子方式应用所有编辑；调用失败时模型保持不变
model_field_add / model_field_rename / model_field_reposition	管理现有笔记类型的字段：添加（可选指定从 0 开始的索引）、重命名（保留内容；卡片模板不会自动更新）、重新定位（调整顺序）。添加和重新定位会更改字段序号并强制执行单向完整同步；仅重命名不会。每个结果都包含 will_force_full_sync，其值反映写入后集合的实际状态（粘性、集合级状态）
model_field_remove	删除该类型所有笔记中的某个字段及其内容。具有破坏性 — 仅在通过 enabled_destructive_tools 启用后显示。强制执行单向完整同步
create_model	创建新的笔记类型
change_note_type	将现有笔记移至其他笔记类型，并按名称重新映射字段（{旧字段: 新字段或 null}）。具有破坏性 — 仅在通过 enabled_destructive_tools 启用后显示。分两步执行：dry_run=true 会返回已解析的计划（映射、丢弃的字段、已移除的卡片），然后使用相同的调用设置 dry_run=false 且设置 confirm=true 以应用计划。所有笔记必须共用一个源笔记类型
store_media_file	通过 base64、文件路径或 URL 存储媒体文件（图像/音频）。文件路径会根据媒体类型允许列表进行验证；URL 会进行 SSRF 检查
get_media_files_names	列出匹配指定模式的媒体文件
delete_media_file	将媒体文件移至 Anki 垃圾桶（可通过 Check Media 恢复）

FSRS 工具

工具	描述
get_fsrs_params	获取牌组预设的 FSRS 调度器参数
set_fsrs_params	更新 FSRS 参数（权重、期望保留率、最大间隔）
get_card_memory_state	获取卡片的 FSRS 记忆状态（稳定性、难度、可检索性）
optimize_fsrs_params	使用 Anki 内置优化器运行 FSRS 参数优化

GUI 工具

这些工具与 Anki 用户界面交互：

工具	描述
gui_browse	使用搜索查询打开卡片浏览器
gui_add_cards	打开添加卡片对话框
gui_edit_note	打开特定笔记的编辑器
gui_current_card	获取当前显示卡片的信息
gui_show_question	显示当前卡片的正面
gui_show_answer	显示当前卡片的背面
gui_select_card	在复习器中选择特定卡片
gui_deck_browser	导航至牌组浏览器
gui_undo	撤销上一次操作
gui_deck_review	在 Anki 自带的复习窗口中打开牌组。选择加入 — 除非通过 enabled_opt_in_tools 选择加入，否则此工具会隐藏
gui_answer_card	按下复习器中所示卡片的评分按钮，实现免手动评分。选择加入 — 除非通过 enabled_opt_in_tools 选择加入，否则此工具会隐藏

默认情况下，gui_current_card 不再返回笔记的 answer/fields — 传入 include_answer=true 即可获取。

资源

资源	URI	描述
system_info	anki://system-info	Anki 版本、配置文件和调度器信息
query_syntax	anki://query-syntax	Anki 搜索查询语法参考
schema	anki://schema	数据模型文档（实体、字段、关系）
stats_today	anki://stats/today	今日学习统计数据
stats_forecast	anki://stats/forecast	未来 30 天的复习预测
stats_collection	anki://stats/collection	全部内容集合的统计数据
fsrs_config	anki://fsrs/config	FSRS 配置摘要和参数

提示词

提示词	描述
review_session	引导式复习工作流。参数：deck_name（默认值为 Default）、card_limit（默认值为 20）、review_style — interactive、quick、voice 或 gui
twenty_rules	Piotr Woźniak 博士的 知识构建的二十条规则（SuperMemo），作为助手编写卡片的指导。无需参数

要求

• Anki 25.07 或更高版本（附带 Python 3.13）
• Anki 25.02 及更早版本附带 Python 3.9，不受支持 — MCP SDK 要求 Python 3.10+ (#8)

架构

此插件在后台线程中运行 MCP 服务，使用两种独立传输方式：本地 HTTP（FastMCP + uvicorn）和远程隧道（使用内存传输的 WebSocket 中继）。两者共用同一个 FastMCP 服务实例。所有 Anki 操作都通过队列系统桥接至 Qt 主线程，沿用 AnkiConnect 已验证的相同模式。

详情请参阅 Anki 插件开发文档。

开发

运行 E2E 测试

E2E 测试使用 headless-anki 在 Docker 中运行的真实 Anki 实例。

# Install test dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

# Build the addon
./package.sh

# Start Anki container
cd .docker && docker compose up -d && cd ..

# Run tests (waits for server automatically)
pytest tests/e2e/ -v

# Stop container
cd .docker && docker compose down

也可以使用 Makefile 快捷命令：

make e2e        # Build, start container, run tests, stop
make e2e-up     # Just start container
make e2e-test   # Just run tests
make e2e-down   # Just stop container

CI

每次推送至任意分支以及向 main 提交 PR 时，都会自动运行 E2E 测试。请参阅 .github/workflows/e2e.yml。

许可证

AGPL-3.0-or-later

链接

• ankimcp.ai - 项目主页
• MCP 协议 - Model Context Protocol 规范
• Anki 插件文档 - Anki 官方插件开发文档