ANKI-MCP

Name: ANKI-MCP
Author: nietus

作者：nietus34 星标更新：2025-10-21

安装使用来源：spider==github.com

项目介绍

anki-mcp

用于 Anki 的 MCP 服务器。此服务器允许通过模型上下文协议（MCP）与 Anki 进行交互。它使用户能够以编程方式管理闪卡、卡片组以及复习过程。

预备条件

安装了 Node.js 和 npm。
在 Anki 中安装并运行了 AnkiConnect 插件。
对于音频功能：Azure API 密钥（在 .env 文件中设置为 AZURE_API_KEY）和 Anki 媒体目录（设置为 ANKI_MEDIA_DIR）。

设置和执行

强烈建议本地运行，因为 AnkiConnect 只能在本地工作。

仅在 Windows 上进行了测试。

通过 `npx` 本地运行

如果您只想使用该工具而不进行开发，您可以使用 npx 在本地启动一个 MCP STDIO 服务器：

npx -y github:nietus/anki-mcp

这可以在桌面 MCP 客户端（如 Msty Studio 或其他客户端）中使用。

通过源代码本地运行

或者，您可以通过以下步骤使用源代码在本地运行：

克隆仓库：

git clone https://github.com/nietus/anki-mcp

安装依赖项：
```
npm install
```
构建项目
```
npm run build
```
设置音频功能（如果要使用音频工具）：

在根目录创建一个 .env 文件，并添加您的 Azure API 密钥和 Anki 媒体目录：
```
AZURE_API_KEY=your_azure_api_key_here
ANKI_MEDIA_DIR=path/to/your/anki/media/directory
```
对于 Anki 媒体目录，请使用您的 Anki 收藏夹.media 文件夹的路径。这是存储音频文件的位置。如果有问题，请直接将其粘贴到代码中。
- Windows 示例：C:\Users\username\AppData\Roaming\Anki2\User 1\collection.media
- macOS 示例：/Users/username/Library/Application Support/Anki2/User 1/collection.media
- Linux 示例：/home/username/.local/share/Anki2/User 1/collection.media
注意： ANKI_MEDIA_DIR 是必需的，以便正确生成音频，因为 Anki 需要在其媒体收藏夹中找到音频文件。
与 Cursor 设置集成（用于本地执行）：

要使用 Cursor 启动本地构建的 anki-mcp，需要告诉 Cursor 如何启动服务器。以下是您可以在 Cursor 设置中访问的示例配置。替换 YOUR_USERNAME 并根据需要调整路径，如果您将 anki-mcp 克隆到了下载文件夹以外的位置。

Windows:
```
"anki": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "c:/Users/YOUR_USERNAME/Downloads/anki-mcp/build/client.js"
    ]
}
```
使用 .mcpb 包与 Claude Desktop 集成：

推荐的方式是将此服务器作为 MCP 扩展包（.mcpb 文件）安装到 Claude Desktop 中。
1. 构建并打包扩展：
```
npm install
npm run build
npm run pack:mcpb
```
  这将在 dist/anki-mcp.mcpb 中生成一个文件。
2. 在 Claude Desktop 中安装包：
  - 打开 Claude Desktop。
  - 前往 设置 → 扩展。
  - 将 dist/anki-mcp.mcpb 文件拖放到扩展面板中。
  Claude 将自动处理服务器的启动。
3. 配置环境变量：
  
  在安装过程中提示时，提供您的 AZURE_API_KEY 和 ANKI_MEDIA_DIR（指向您的 Anki collection.media 文件夹的路径）。这些对于音频功能和媒体文件处理是必需的。
这就是全部！不需要手动配置——一旦安装了 .mcpb 包，Claude Desktop 将为您管理服务器。 macOS / Linux:
```
"anki": {
      "command": "bash",
      "args": [
        "-c",
        "node /Users/YOUR_USERNAME/Downloads/anki-mcp/build/client.js"
      ]
    }
```

创建一个 Claude Desktop 扩展包 (.mcpb)

如果您希望在 Claude Desktop 内实现一键安装，可以将此服务器打包为 MCP 包：

安装依赖项并构建项目：
```
npm install
npm run build
```
生成 .mcpb 包（需要 @anthropic-ai/mcpb CLI，期望 Node.js 18+）：
```
npm run pack:mcpb
```

脚本会编译服务器（build/），复制运行时依赖项，并生成 dist/anki-mcp.mcpb。将该文件拖放到 Claude Desktop 的设置 → 扩展面板中以进行安装。在提示时，提供 Azure 语音 API 密钥和 Anki 媒体目录，以便音频工具可以将文件保存到您的 collection.media 文件夹中。

可用工具

要调试工具，请使用

npm run inspector

服务器提供了以下工具来与 Anki 进行交互：

update_cards：
- 描述：在用户回答您提问的卡片后，使用此工具标记它们已回答并更新其难度。
- 输入：答案数组，每个答案包含 cardId（数字）和 ease（数字，1-4）。
add_card：
- 描述：在 Anki 中创建一张新的闪卡。仅用于创建新卡片，不用于更新现有卡片（如果卡片已经存在，将会抛出错误）。对于更新现有卡片，请使用 update_note_fields 并提供 noteId。注释内容使用 HTML。
  - 换行：<br>
  - 代码：<pre style="background-color: transparent; padding: 10px; border-radius: 5px;">
  - 列表：<ol> 和 <li>
  - 加粗：<strong>
  - 斜体：<em>
- 输入：
  - fields：（对象）键为字段名称（例如，“汉字”，“拼音”），值为其 HTML 内容的对象。
  - modelName：（字符串）要使用的 Anki 笔记类型（模型）的名称。
  - deckName：（可选字符串）要添加卡片的卡片组的名称。默认为当前卡片组或“默认”。
  - tags：（可选字符串数组）要添加到笔记的标签列表。
add_card_with_audio：
- 描述：使用 Azure TTS 自动生成音频，在 Anki 中创建一张新的闪卡。仅用于创建新卡片，不用于更新现有卡片（如果卡片已经存在，将会抛出错误）。对于更新现有卡片的音频，请使用 update_card_with_audio 并提供 noteId。
- 输入：
  - fields，modelName，deckName，tags：与 add_card 相同。
  - sourceField：（字符串）包含要生成音频的文本的字段名称。
  - audioField：（字符串）将存储生成音频的字段名称。
  - language：（可选字符串）TTS 的语言代码（例如，'en'，'es'，'fr'）。默认为 'en'。
- 支持的语言：en, es, fr, de, it, ja, ko, pt, ru, zh, ar, nl, hi, tr, pl, sv, fi, da, no, cs, hu, el, he, th, vi, id, ms, ro。
update_card_with_audio：
- 描述：通过从指定字段生成音频并将其添加到音频字段来更新现有的卡片。仅用于已存在的卡片（您必须拥有 noteId）。对于创建带有音频的新卡片，请使用 add_card_with_audio。
- 输入：
  - noteId：（数字）要更新的 Anki 笔记的 ID。
  - sourceField：（字符串）包含要生成音频的文本的字段名称。
  - audioField：（字符串）将存储生成音频的字段名称。
  - language：（可选字符串）TTS 的语言代码。默认为 'en'。
get_due_cards：
- 描述：返回给定数量的待复习卡片。
- 输入：num（数字）。
get_new_cards：
- 描述：返回给定数量的新且未见过的卡片。
- 输入：num（数字）。
get_deck_names：
- 描述：获取所有 Anki 卡片组名称的列表。
- 输入：无。
find_cards：
- 描述：使用原始 Anki 查询搜索卡片。返回详细的卡片信息，包括字段。
- 输入：query（字符串，例如，'deck:Default -tag:test'，或 '"deck:My Deck" tag:important'）。为了筛选空字段，使用 '-FieldName:_*'（例如，'-Hanzi:_*'）。
update_note_fields：
- 描述：更新现有 Anki 笔记的特定字段。仅当您已经拥有现有卡片的 noteId 时使用。对于创建新卡片，请使用 add_card。
- 输入：noteId（数字），fields（对象，例如，{"正面": "新问题", "背面": "新答案"}）。
create_deck：
- 描述：创建一个新的 Anki 卡片组。
- 输入：deckName（字符串）。
bulk_update_notes：
- 描述：推荐用于多张卡片：在一个操作中更新多个现有 Anki 笔记的特定字段。比逐个更新卡片更高效。仅当您拥有已存在卡片的 noteIds 时使用。对于批量创建新卡片，请使用 add_bulk。尽可能在单个操作中完成所有更新。
- 输入：notes 数组，其中每个笔记包含 noteId（数字）和 fields（对象）。
get_model_names：
- 描述：列出所有可用的 Anki 笔记类型/模型名称。
- 输入：无。
get_model_details：
- 描述：检索指定笔记类型的字段、卡片模板和 CSS 样式。
- 输入：modelName（字符串）。
get_deck_model_info：
- 描述：检索指定卡片组内使用的笔记类型（模型）的信息。有助于确定是否使用单一模型、多个模型，还是卡片组为空或不存在。
- 输入：deckName（字符串）。
- 输出：一个包含 deckName，状态（例如，“找到单一模型”，“找到多个模型”，“未找到笔记”，“未找到卡片组”），以及条件性 modelName（字符串）或 modelNames（字符串数组）的对象。
add_note_type_field：
- 描述：向笔记类型添加一个新字段。
- 输入：modelName（字符串），fieldName（字符串）。
remove_note_type_field：
- 描述：从笔记类型中移除一个现有字段。
- 输入：modelName（字符串），fieldName（字符串）。
rename_note_type_field：
- 描述：重命名笔记类型中的一个字段。
- 输入：modelName（字符串），oldFieldName（字符串），newFieldName（字符串）。
reposition_note_type_field：
- 描述：更改笔记类型中字段的顺序（索引）。
- 输入：modelName（字符串），fieldName（字符串），index（数字）。
update_note_type_templates：
- 描述：更新笔记类型的 HTML 模板（例如，正面和背面）。
- 输入：modelName（字符串），templates（对象，例如，{"卡片 1": {"正面": "html", "背面": "html"}}）。
update_note_type_styling：
- 描述：更新笔记类型的 CSS 样式。
- 输入：modelName（字符串），css（字符串）。
create_model：
- 描述：创建一个新的 Anki 笔记类型（模型）。
- 输入：modelName（字符串），fieldNames（字符串数组），cardTemplates（对象数组，每个对象包含 Name，正面，背面 HTML 字符串），css（可选字符串），isCloze（可选布尔值，默认为 false），modelType（可选字符串，默认为 'Standard'）。
add_bulk：
- 描述：推荐用于多张卡片：在一个操作中向 Anki 添加多张新的闪卡。比逐个添加卡片更高效。仅用于创建新卡片，不用于更新现有卡片（如果卡片已经存在，将会抛出错误）。对于更新现有卡片，请使用 bulk_update_notes 并提供 noteIds。尽可能在单个操作中完成所有添加。必须使用 HTML 格式化卡片内容。
- 输入：notes 数组，其中每个笔记对象包含：
  - fields：（对象）键为字段名称，值为其 HTML 内容的对象。
  - modelName：（字符串）为此笔记使用的 Anki 笔记类型（模型）的名称。
  - deckName：（可选字符串）此笔记的卡片组名称。默认为 '默认'。
  - tags：（可选字符串数组）此笔记的标签列表。

更多详情请参阅 Anki 集成 | Smithery