Anki MCP Server

🚀 Anki MCP Server

本项目是一个基于Model Context Protocol（MCP）的服务器，它能让AI助手与间隔重复记忆卡片应用Anki进行交互。借助自然语言交互，能让你的Anki使用体验焕然一新，就像拥有一位私人导师。AI助手不只是简单地展示问题和答案，还能解释概念、让学习过程更具吸引力和人性化、提供上下文信息，并适应你的学习风格。它还能即时创建和编辑笔记，将你的学习会话变成动态的对话。更多功能即将推出！

⚠️ 重要提示

本项目已重命名并迁移：

• 包名：anki-mcp-http → @ankimcp/anki-mcp-server
• 命令：anki-mcp-http → ankimcp 或 anki-mcp-server
• 仓库：anki-mcp/anki-mcp-desktop → ankimcp/anki-mcp-server

旧的 anki-mcp-http 包为了向后兼容会继续发布，但已被弃用。请迁移到新的包。

了解更多变更信息 →

💡 使用建议

本项目处于积极开发的Beta阶段，API和功能可能会发生变化，请谨慎使用。

🚀 快速开始

本MCP服务器处于积极开发的Beta阶段，API和功能可能会发生变化。它能让AI助手与间隔重复记忆卡片应用Anki进行交互。要获取使用此MCP服务器与Claude Desktop的全面指南、实际示例和分步教程，请访问： ankimcp.ai - 包含实际示例和用例的完整文档

✨ 主要特性

• 自然语言交互：将你的Anki体验转变为自然语言交互，就像拥有一位私人导师。AI助手不仅能呈现问题和答案，还能解释概念、使学习过程更具吸引力和人性化、提供上下文信息，并适应你的学习风格。
• 动态笔记管理：可以即时创建和编辑笔记，将学习会话变成动态的对话。
• 多工具支持：提供了丰富的工具，涵盖复习与学习、卡组管理、笔记管理和媒体管理等多个方面。

📦 安装指南

此服务器有两种运行模式：

• 本地模式（STDIO） - 适用于本地计算机上的Claude Desktop（推荐大多数用户使用）
• 远程模式（HTTP） - 适用于基于Web的AI助手，如ChatGPT或Claude.ai

选项1：MCPB捆绑包（推荐 - 本地模式）

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

1. 从发布页面下载最新的 .mcpb 捆绑包。
2. 在Claude Desktop中安装扩展：
   • 方法1：转到设置 → 扩展，然后拖放 .mcpb 文件。
   • 方法2：转到设置 → 开发者 → 扩展 → 安装扩展，然后选择 .mcpb 文件。
3. 如有需要，配置AnkiConnect URL（默认为 http://localhost:8765）。
4. 重启Claude Desktop。

选项2：使用STDIO的NPM包（适用于其他MCP客户端）

如果你想将Anki与诸如 Cursor IDE、Cline 或 Zed Editor 等MCP客户端一起使用，请使用带有 --stdio 标志的npm包：

支持的客户端：

• Cursor IDE - 由AI驱动的代码编辑器
• Cline - 用于AI辅助的VS Code扩展
• Zed Editor - 快速、现代的代码编辑器
• 其他支持STDIO传输的MCP客户端

配置 - 选择一种方法：

方法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"
      }
    }
  }
}

选项3：HTTP模式（适用于远程AI助手）

如果你想在浏览器中使用Anki与ChatGPT或Claude.ai，请使用此模式，它可以让基于Web的AI工具连接到你本地的Anki。

工作原理（简单解释）：

1. 在你的计算机（安装了Anki的地方）上运行一个小型服务器。
2. 使用内置的 --ngrok 标志自动创建一个公共隧道URL。
3. 将该URL分享给ChatGPT或Claude.ai。
4. 现在，AI就可以通过互联网与你的Anki进行通信了！

v0.8.0新增功能：集成了ngrok支持，使用 --ngrok 标志，无需单独运行ngrok！

设置 - 选择一种方法：

方法1：使用npx（推荐 - 无需安装）

# 快速开始
npx @ankimcp/anki-mcp-server

# 使用ngrok隧道（推荐用于基于Web的AI）
npx @ankimcp/anki-mcp-server --ngrok

# 使用自定义选项
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765

方法2：全局安装

# 一次性安装
npm install -g @ankimcp/anki-mcp-server

# 运行服务器
ankimcp

# 使用ngrok隧道（推荐用于基于Web的AI）
ankimcp --ngrok

# 使用自定义选项
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

选项4：从源代码手动安装（本地模式）

适用于开发或高级使用场景：

npm install
npm run build

💻 使用示例

基础用法

# 搜索特定卡组中的笔记
findNotes(query: "deck:Spanish")

# 获取笔记的详细信息
notesInfo(notes: [1234567890, 1234567891])

# 更新笔记的字段（支持HTML内容）
updateNoteFields(note: {
  id: 1234567890,
  fields: {
    "Front": "<b>¿Cómo estás?</b>",
    "Back": "How are you?"
  }
})

# 删除笔记（需要确认）
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" - 西班牙语卡组中带有动词标签的笔记（AND）
• "deck:Spanish OR deck:French" - 来自任一卡组的笔记

📚 详细文档

可用工具

复习与学习

• sync - 与AnkiWeb同步
• get_due_cards - 获取待复习的卡片
• present_card - 展示待复习的卡片
• rate_card - 对卡片的表现进行评分

卡组管理

• list_decks - 显示可用的卡组
• createDeck - 创建新的卡组

笔记管理

• addNote - 创建新的笔记
• findNotes - 使用Anki查询语法搜索笔记
• notesInfo - 获取笔记的详细信息（字段、标签、CSS）
• updateNoteFields - 更新现有笔记的字段（支持CSS，支持HTML）
• deleteNotes - 删除笔记及其关联的卡片

媒体管理

• mediaActions - 管理媒体文件（音频/图像）
  • storeMediaFile - 从base64数据、文件路径或URL上传媒体
  • retrieveMediaFile - 以base64形式下载媒体
  • getMediaFilesNames - 列出媒体文件，可选择进行模式过滤
  • deleteMediaFile - 删除媒体文件

💡 图片使用最佳实践：

• ✅ 使用文件路径（例如，/Users/you/image.png） - 快速高效
• ✅ 使用URL（例如，https://example.com/image.jpg） - 直接下载
• ❌ 避免使用base64 - 极其缓慢且消耗大量令牌

模型/模板管理

• modelNames - 列出笔记类型
• modelFieldNames - 获取笔记类型的字段
• modelStyling - 获取笔记类型的CSS样式

环境变量（可选）

属性	详情
ANKI_CONNECT_URL	AnkiConnect的URL，默认为 http://localhost:8765
ANKI_CONNECT_API_VERSION	API版本，默认为 6
ANKI_CONNECT_API_KEY	如果在AnkiConnect中配置了API密钥，则需要设置该变量
ANKI_CONNECT_TIMEOUT	请求超时时间（毫秒），默认为 5000

连接到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文档。

开发

传输模式

此服务器通过单独的入口点支持两种MCP传输模式：

STDIO模式（默认）

• 适用于本地MCP客户端，如Claude Desktop
• 使用标准输入/输出进行通信
• 入口点：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/（根路径）

构建

npm run build  # 一次性构建，在dist/目录中创建两个入口点

HTTP模式配置

环境变量：

• PORT - HTTP服务器端口（默认：3000）
• HOST - 绑定地址（默认：127.0.0.1，仅本地访问）
• ALLOWED_ORIGINS - 允许的CORS来源的逗号分隔列表（默认：localhost）
• LOG_LEVEL - 日志级别（默认：info）

安全：

• 源头部验证（防止DNS重绑定攻击）
• 默认绑定到本地主机（127.0.0.1）
• 当前版本无身份验证（计划支持OAuth）

示例：运行模式

# 开发 - STDIO模式（监视模式，自动重建）
npm run start:dev:stdio

# 开发 - HTTP模式（监视模式，自动重建）
npm run start:dev:http

# 生产 - STDIO模式
npm run start:prod:stdio
# 或者
node dist/main-stdio.js

# 生产 - HTTP模式
npm run start:prod:http
# 或者
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 以删除开发依赖项（将捆绑包从约47MB优化到约10MB）。

输出文件将命名为 anki-mcp-server-X.X.X.mcpb，可以进行分发以实现一键安装。

捆绑内容

MCPB包包括：

• 编译后的JavaScript（dist/ 目录 - 包括两个入口点）
• 仅生产依赖项（node_modules/ - 通过 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调试MCP服务器，并从你的IDE（WebStorm、VS Code等）附加调试器。

HTTP模式注意事项：使用MCP Inspector测试HTTP模式（可流式传输的HTTP）时，使用 "连接类型：通过代理" 以避免CORS错误。

步骤1：在MCP Inspector中配置调试服务器

mcp-inspector-config.json 已经包含了一个调试服务器配置：

{
  "mcpServers": {
    "stdio-server-debug": {
      "type": "",
      "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. 选择 Attach to 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              # 构建项目（将TypeScript编译为JavaScript）
npm run start:dev:stdio    # STDIO模式，监视模式（自动重建）
npm run start:dev:http     # HTTP模式，监视模式（自动重建）
npm run type-check         # 运行TypeScript类型检查
npm run lint               # 运行ESLint
npm run mcpb:bundle        # 同步版本、清理、构建并创建MCPB捆绑包

NPM包测试（本地）

在发布之前，在本地测试npm包：

# 1. 创建本地包
npm run pack:local         # 构建并创建 @ankimcp/anki-mcp-server-*.tgz

# 2. 从本地包全局安装
npm run install:local      # 从 ./@ankimcp/anki-mcp-server-*.tgz 安装

# 3. 测试命令
ankimcp                    # 在端口3000上运行HTTP服务器

# 4. 测试完成后卸载
npm run uninstall:local    # 移除全局安装

测试命令

npm test              # 运行所有测试
npm run test:unit     # 仅运行单元测试
npm run test:tools    # 运行特定工具的测试
npm run test:workflows # 运行工作流集成测试
npm run test:e2e      # 运行端到端测试
npm run test:cov      # 运行测试并生成覆盖率报告
npm run test:watch    # 在监视模式下运行测试
npm run test:debug    # 运行测试并使用调试器
npm run test:ci       # 为CI运行测试（静默，带覆盖率）

测试覆盖率

项目对以下方面保持最低70%的覆盖率阈值：

• 分支
• 函数
• 行
• 语句

覆盖率报告将在 coverage/ 目录中生成。

版本控制

本项目遵循语义化版本控制，采用1.0之前的开发方法：

• 0.x.x - Beta/开发版本（当前阶段）

  • 0.1.x - 错误修复和补丁
  • 0.2.0+ - 新功能或小改进
  • 在0.x版本中，允许进行重大更改

• 1.0.0 - 第一个稳定版本

  • 将在API稳定并经过测试后发布
  • 重大更改将需要进行主版本升级（2.0.0等）

当前状态：0.8.0 - 积极的Beta开发阶段。新功能包括集成ngrok隧道（--ngrok 标志）、用于基于证据的抽认卡创建的 twenty_rules 提示、媒体文件管理和改进的提示系统。API可能会根据反馈和测试进行更改。

类似项目

如果你正在探索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官方网站

🔧 技术细节

已知问题

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

关键限制

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

⚠️ 重要提示：使用 updateNoteFields 更新笔记时，如果笔记当前正在Anki的浏览器窗口中查看，更新将无声失败。这是上游AnkiConnect的限制。

解决方法：在更新之前，始终关闭浏览器或导航到其他笔记。有关更多详细信息和其他已知问题，请参阅 完整文档。

重要注意事项

CSS和HTML处理

• notesInfo 工具返回CSS样式信息，以确保正确渲染。
• updateNoteFields 工具支持字段中的HTML内容，并保留CSS样式。
• 每个笔记模型都有自己的CSS样式 - 使用 modelStyling 获取特定模型的CSS。

更新警告

⚠️ 重要提示：使用 updateNoteFields 时，在更新期间请勿在Anki的浏览器中查看笔记，否则字段将无法正确更新。在更新之前关闭浏览器或切换到其他笔记。有关更多详细信息，请参阅 已知问题。

删除安全

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

📄 许可证

本项目根据GNU Affero通用公共许可证v3.0或更高版本（AGPL-3.0或更高版本）许可。

为什么选择AGPL-3.0？

选择此许可证是为了在未来可能的集成场景中与Anki的AGPL-3.0许可证保持兼容。

这意味着：

• 个人使用：可以自由使用该软件。
• 为他人提供服务：必须提供源代码访问（AGPL第13节）。
• 修改和分发：必须在AGPL-3.0或更高版本下分享你的改进。

有关完整的许可条款，请参阅 LICENSE 文件。

第三方归属

• 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技术。所有商标、服务标志、商号、产品名称和标志均为其各自所有者的财产。