金大哥 - anki-mcp-server MCP 详情

article

README

🚀 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和功能可能会发生变化，请谨慎使用。

通过 Model Context Protocol 实现 Anki 与AI助手的无缝集成

🚀 快速开始

本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服务器最简单的方法：

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

工作原理（简单解释）：

在你的计算机（安装了Anki的地方）上运行一个小型服务器。
使用内置的 --ngrok 标志自动创建一个公共隧道URL。
将该URL分享给ChatGPT或Claude.ai。
现在，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

此命令将：

将 package.json 中的版本同步到 manifest.json。
删除旧的 .mcpb 文件。
构建TypeScript项目。
将 dist/ 和 node_modules/ 打包到一个 .mcpb 文件中。
运行 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

转到 运行 → 编辑配置
添加一个新的 附加到Node.js/Chrome 配置
将端口设置为 9229
点击调试以附加

VS Code

打开调试面板（Ctrl+Shift+D / Cmd+Shift+D）
选择 调试MCP服务器（附加） 配置
按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

转到 运行 → 编辑配置
点击 + 按钮并选择 附加到Node.js/Chrome
配置：
- 名称：Attach to Anki MCP (Claude Desktop)
- 主机：localhost
- 端口：9229
- 附加到：Node.js < 8 或 Chrome or Node.js > 6.3（取决于WebStorm版本）
点击确定
点击调试（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              # 构建项目（将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集成或计划显著扩展功能，本项目的架构方法使其更易于长期维护和扩展。

有用链接

🔧 技术细节

已知问题

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

关键限制

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

⚠️ 重要提示：使用 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技术。所有商标、服务标志、商号、产品名称和标志均为其各自所有者的财产。

anki-mcp-server

README

🚀 Anki MCP Server

🚀 快速开始

✨ 主要特性

📦 安装指南

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

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

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

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

💻 使用示例

基础用法

高级用法

Anki查询语法示例

📚 详细文档

可用工具

复习与学习

卡组管理

笔记管理

媒体管理

模型/模板管理

环境变量（可选）

连接到Claude Desktop（本地模式）

配置

配置文件位置

开发

传输模式

STDIO模式（默认）

HTTP模式（可流式传输的HTTP）

构建

HTTP模式配置

构建MCPB捆绑包

捆绑内容

在Claude Desktop中记录日志

调试MCP服务器

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

步骤2：启动调试服务器

步骤3：从你的IDE附加调试器

WebStorm

VS Code

步骤4：设置断点并调试

使用Claude Desktop进行调试

步骤1：为调试配置Claude Desktop

步骤2：重启Claude Desktop

步骤3：从你的IDE附加调试器

WebStorm

VS Code

步骤4：实时调试

构建命令

NPM包测试（本地）

测试命令

测试覆盖率

版本控制

类似项目

scorzeth/anki-mcp-server

nailuoGG/anki-mcp-server

有用链接

🔧 技术细节

已知问题

关键限制

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

重要注意事项

CSS和HTML处理

更新警告

删除安全

📄 许可证

为什么选择AGPL-3.0？

第三方归属

运行方式说明

托管运行

本地运行 / 其它方式