anki-mcp

用于 Anki 的 MCP 服务器。此服务器允许通过 Model Context Protocol (MCP) 与 Anki 进行交互。它使用户能够以编程方式管理闪卡、牌组和复习过程。

前提条件

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

设置和执行

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

仅在 Windows 上进行了测试。

本地运行步骤：

1. 克隆仓库：

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

2. 安装依赖项：

   bash
   npm install

3. 构建项目

   bash
   npm run build

4. 设置音频功能（如果您想使用音频工具）：

   在根目录下创建一个 .env 文件，并添加您的 Azure API 密钥和 Anki 媒体目录路径：

   AZURE_API_KEY=your_azure_api_key_here
   ANKI_MEDIA_DIR=path/to/your/anki/media/directory

   对于 Anki 媒体目录，请使用指向您的 Anki collection.media 文件夹的路径。这是存储音频文件的地方。如果遇到问题，请直接将路径粘贴到代码中。

   • Windows 示例：C:UsersusernameAppDataRoamingAnki2User 1collection.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 需要在其媒体集合中找到音频文件。

5. 与 Cursor 设置集成（用于本地执行）：

   要使用 Cursor 运行您本地构建的 anki-mcp，您需要告诉 Cursor 如何启动服务器。以下是一些示例配置，您可以在 Cursor 设置中访问这些配置。替换 YOUR_USERNAME 并根据需要调整路径（如果您将 anki-mcp 克隆到了不同于 Downloads 的位置）。

   Windows：

   json
   "anki": {
   "command": "cmd",
   "args": [
   "/c",
   "node",
   "c:/Users/YOUR_USERNAME/Downloads/anki-mcp/build/client.js"
   ]
   }

   macOS / Linux：

   json
   "anki": {
   "command": "bash",
   "args": [
   "-c",
   "node /Users/YOUR_USERNAME/Downloads/anki-mcp/build/client.js"
   ]
   }

可用工具

要调试工具，请使用

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: (对象) 一个对象，其中键是字段名称（例如，“Hanzi”，“Pinyin”），值是它们的 HTML 内容。
    • modelName: (字符串) 要使用的 Anki 笔记类型（模型）的名称。
    • deckName: (可选字符串) 要将卡片添加到的牌组名称。默认为当前牌组或“Default”。
    • tags: (可选字符串数组) 要添加到笔记的一组标签。

• add_card_with_audio:- 描述：在 Anki 中创建一张新的闪卡，并使用 Azure TTS 自动生成音频。仅用于创建新卡片，不应用于更新现有卡片（如果卡片已存在将抛出错误）。对于更新现有卡片上的音频，请使用 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 (对象，例如 {"Front": "New Q", "Back": "New A"})。

• 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，status（例如 "single_model_found", "multiple_models_found", "no_notes_found", "deck_not_found"），以及条件性地 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 (对象，例如 {"Card 1": {"Front": "html", "Back": "html"}})。

• update_note_type_styling:

  • 描述：更新笔记类型的 CSS 样式。
  • 输入：modelName (字符串), css (字符串)。

• create_model:

  • 描述：创建一个新的 Anki 笔记类型（模型）。
  • 输入：modelName (字符串), fieldNames (字符串数组), cardTemplates (对象数组，每个对象包含 Name, Front, Back HTML 字符串), css (可选字符串), isCloze (可选布尔值，默认为 false), modelType (可选字符串，默认为 Standard)。

• add_bulk:

  • 描述：推荐用于多张卡片：在一次操作中向 Anki 添加多个新的闪卡。比逐个添加卡片更高效。仅用于创建新卡片，不应用于更新现有卡片（对于任何已存在的卡片将抛出错误）。要更新现有卡片，请使用带有 noteIds 的 bulk_update_notes。尽可能在单次操作中完成所有添加。必须使用 HTML 格式化卡片内容。
  • 输入：一个 notes 数组，其中每个笔记对象包含：
    • fields: (对象) 一个键为字段名、值为其 HTML 内容的对象。
    • modelName: (字符串) 该笔记使用的 Anki 笔记类型（模型）名称。
    • deckName: (可选字符串) 该笔记的牌组名称。默认为 Default。
    • tags: (可选字符串数组) 该笔记的标签列表。

更多详细信息请参见这里 Anki Integration | Smithery