Anki MCP Server

Anki MCP 服务

一个模型上下文协议（MCP）服务，可通过 AnkiConnect 让大模型与 Anki 闪卡软件交互。

功能

工具

• anki_check_connection - 检查 AnkiConnect 是否可访问
• anki_list_decks - 列出所有可用的 Anki 牌组，可选择同时显示牌组 ID
• anki_create_deck - 创建新的 Anki 牌组
• anki_list_tags - 列出当前牌组集合中使用的所有标签
• anki_add_note_tags - 为一个或多个笔记添加标签
• anki_remove_note_tags - 从一个或多个笔记中移除标签
• anki_create_note - 创建新笔记
• anki_batch_create_notes - 一次创建多条笔记
• anki_search_notes - 使用 Anki 查询语法搜索笔记
• anki_get_note_info - 获取笔记的详细信息
• anki_update_note - 更新现有笔记的字段和／或标签
• anki_delete_note - 删除一条或多条笔记
• anki_list_note_types - 列出所有可用的笔记类型
• anki_create_note_type - 创建新的笔记类型
• anki_get_note_type_info - 获取笔记类型的详细结构
• anki_sync - 触发 AnkiWeb 同步；由于完整同步可能合并或覆盖本地和远程集合，必须提供 {"confirm": true}。成功表示 Anki 已接受请求，并不代表 AnkiWeb 已收到数据；Anki 中阻塞的对话框可能会导致同步请求静默排队

为兼容现有客户端，仍可调用 create_note 和 list_decks 等不带前缀的旧工具名称，但新的 Agent 集成应使用 anki_* 名称。

资源

• anki://decks/all - 包含牌组 ID 的完整可用牌组列表
• anki://tags/all - 完整标签列表
• anki://note-types/all - 所有可用笔记类型的列表
• anki://note-types/all-with-schemas - 所有笔记类型的详细结构信息
• anki://note-types/{modelName} - 特定笔记类型的详细结构信息

前置条件

1. 系统已安装 Anki
2. Anki 中已安装 AnkiConnect 插件
3. Node.js 20.11 或更高版本

配置

通过桌面扩展安装（.mcpb）

本仓库支持 Anthropic 桌面扩展（MCPB）。在 Claude Desktop 中使用此服务的最简单方式是安装打包好的 .mcpb 文件。

1. 使用提供的脚本在本地生成 .mcpb 文件：

npm run mcpb

2. 打开 Claude Desktop 设置 → 扩展，将生成的 .mcpb 文件拖入，然后点击安装。

此操作会验证 manifest.json 并生成 .mcpb 归档文件，随后即可按上述步骤安装。有关桌面扩展的更多信息，请参阅 Anthropic 的公告：桌面扩展：一键为 Claude Desktop 安装 MCP 服务。

在 Claude Desktop 中使用

将服务添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server"]
    }
  }
}

使用自定义 AnkiConnect 端口

如果 AnkiConnect 运行在其他端口，可使用 --port 参数指定：

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server", "--port", "8080"]
    }
  }
}

Cline 配置

在 VSCode 的设置文件 cline_mcp_settings.json 中，将服务添加到 Cline MCP 设置中。

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server"]
    }
  }
}

使用自定义 AnkiConnect 端口

对于 Cline，也可以指定自定义端口：

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server", "--port", "8080"]
    }
  }
}

Agent 技能（Claude Code）

安装 Anki 技能，为 Claude Code 提供所有 Anki 工具和工作流的内置知识：

npx skills add nailuoGG/anki-mcp-server@anki

安装后，当你要求 Claude Code 创建闪卡、管理牌组或批量导入笔记时，它会自动使用此技能。

注意： 请勿将打包好的 .mcpb 版本用作 MCP 服务——它会将 Electron 元数据输出到 stdout，从而破坏 MCP stdio 协议。请改用 npx -y anki-mcp-server。

开发

打包桌面扩展（.mcpb）

为 Claude Desktop 创建可分发的桌面扩展包：

npm run mcpb

这会构建项目，并从当前仓库生成 .mcpb 压缩包，同时验证 manifest.json。将其拖入 Claude Desktop 的扩展设置中进行测试。参考：桌面扩展：一键安装 MCP 服务到 Claude Desktop。

发布到 MCP Registry

此服务会在发布新版本时自动发布到 MCP Registry。发布流程包括：

1. 自动化 CI/CD：成功发布后，GitHub Actions 会自动将其发布到 NPM 和 MCP Registry
2. 架构验证：发布前，会根据 MCP 架构验证 server.json 文件
3. 版本同步：确保 package.json、manifest.json 和 server.json 中的版本保持同步
4. 全面测试：发布前进行多版本 Node.js 测试、代码检查和验证
5. Beta 支持：自动发布 Beta 版本以测试新功能

手动验证

你可以在本地验证 MCP 服务配置：

npm run validate-mcp

这会下载最新的 MCP 架构并验证你的 server.json 文件。

手动发布

如果需要手动发布，可以使用 MCP Publisher CLI：

# Install MCP Publisher
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
chmod +x mcp-publisher
sudo mv mcp-publisher /usr/local/bin/

# Login to MCP Registry
mcp-publisher login github-oidc

# Publish to MCP Registry
mcp-publisher publish

设置

1. 安装依赖：

npm install

2. 构建服务：

npm run build

3. 在开发期间自动重新构建：

npm run watch

测试

运行测试套件：

npm test

这会对 MCP 工具架构、结构化工具结果、笔记创建、搜索／更新／删除工作流以及错误处理执行单元测试。这些测试使用模拟的 AnkiConnect 客户端；如需手动进行集成检查，请在运行中的 Anki 实例上使用 MCP Inspector。

MCP 评估

只读 Agent 评估资源位于 evals/。将测试数据加载到一次性 Anki 配置文件中，然后针对 MCP 服务运行 XML 问题，以验证 Agent 能否发现牌组、标签、笔记类型架构、资源和结构化工具结果。

调试

由于 MCP 服务通过 stdio 通信，我们建议使用 MCP Inspector：

npm run inspector

它提供基于浏览器的界面，可用于：

• 监控 MCP 消息
• 测试工具调用
• 查看服务日志
• 调试通信问题

使用示例

1. 创建一个新牌组：

Create a new Anki deck called "Programming"

2. 添加一张基础卡片：

Create an Anki card in the "Programming" deck with:
Front: What is a closure in JavaScript?
Back: A closure is the combination of a function and the lexical environment within which that function was declared.

3. 添加一张填空删除卡片：

Create a cloze card in the "Programming" deck with:
Text: In JavaScript, {{c1::const}} declares a block-scoped variable that cannot be {{c2::reassigned}}.

4. 删除一条笔记：

Delete note ID 1234567890

5. 一次删除多条笔记：

Delete note IDs 1234567890, 9876543210, and 1122334455

6. 为笔记添加标签：

Add tags "review" and "mcp" to note IDs 1234567890 and 9876543210

贡献

1. Fork 此仓库
2. 创建你的功能分支
3. 运行测试：npm test
4. 提交拉取请求

Star 历史

致谢

图标由 macOS Icons 提供

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件