星战科技xingzhan.cloud
返回市场
ANKI-MCP

ANKI-MCP

作者：amidvidy6 星标更新：2025-10-20
安装使用来源：spider==github.com

项目介绍

Anki MCP 服务器

这是一个通过模型上下文协议（MCP）与 Anki 进行交互的 FastMCP 服务器。该服务器提供了全面的工具来管理 Anki 的卡片集、笔记和笔记类型，并具有高级功能，包括基于人工智能的音频生成、批量操作和语义相似性搜索。

使用的外部 API

该项目集成了一些外部 API 来提供增强的功能：

Google Cloud 文本转语音 API

  • 目的：使用 Google 的 Chirp 声音从文本生成高质量音频
  • 用例：为闪卡生成发音音频文件
  • 特性：具有自然发音的高清声音，尤其是对于中文非常出色
  • 设置：需要 GOOGLE_CLOUD_API_KEY 环境变量

AnkiConnect API（本地）

  • 目的：与 Anki 桌面应用程序进行交互
  • 用例：所有 Anki 操作（创建/读取/更新笔记、管理卡片集等）
  • 特性：通过 HTTP API 实现完整的 Anki 功能
  • 设置：必须安装 AnkiConnect 插件并且 Anki 必须正在运行

设置

  1. 使用 uv 安装依赖项：

    uv sync

  2. 确保 Anki 正在运行且已安装 AnkiConnect 插件：

    • 在 Anki 中，前往 工具 > 插件 > 获取插件
    • 输入代码：2055492159
    • 重启 Anki

  3. （可选）设置用于音频生成的 API 密钥：

    # 用于 Google Cloud TTS 的音频生成
export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

  4. 运行服务器：

    uv run server.py

Claude 桌面集成

要将此 MCP 服务器与 Claude 桌面一起使用，请在您的 claude_desktop_config.json 文件中添加以下配置：

配置位置

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json

配置示例

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ],
      "env": {
        "GOOGLE_CLOUD_API_KEY": "your-google-cloud-api-key-here"
      }
    }
  }
}

设置步骤

  1. 确保已安装依赖项：确保您已在 anki-mcp 目录中运行了 uv sync
  2. 找到您的配置文件：在上述位置找到配置文件（如果不存在则创建）
  3. 更新路径：将 /path/to/your/anki-mcp/ 替换为您实际的 anki-mcp 目录路径
  4. 添加您的 API 密钥：
    • 将 your-google-cloud-api-key-here 替换为您的实际 Google Cloud API 密钥（用于音频生成）
  5. 重启 Claude 桌面 以使更改生效

重要提示

  • 确保在使用工具之前 Anki 正在运行 并且已安装 AnkiConnect 插件
  • uv 命令会自动处理 Python 环境和依赖项
  • 确保系统上已安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）

替代方案：使用环境变量

如果您希望将 API 密钥保存在 shell 环境中，可以省略 env 部分：

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ]
    }
  }
}

然后在您的 shell 中设置环境变量：

export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

验证

配置完成后，重启 Claude 桌面，您应该可以在对话中看到 Anki MCP 工具。您可以通过请求 Claude 列出您的 Anki 卡片集或尝试任何可用工具来进行验证。

可用工具

list_decks

列出所有可用的 Anki 卡片集及其数量。

参数：无

返回值：格式化的字符串，包含所有卡片集名称及总数

get_deck_notes

从特定卡片集中检索所有笔记/卡片及其详细信息。

参数：

  • deck_name (str)：要检索笔记的 Anki 卡片集名称

返回值：关于所有笔记的详细信息，包括模型名称、标签和字段值

get_deck_sample

获取卡片集中的随机样本笔记，以了解典型的笔记结构。

参数：

  • deck_name (str)：要采样的 Anki 卡片集名称
  • sample_size (int, 可选)：要采样的笔记数量（1-50，默认：5）

返回值：关于采样笔记的详细信息

get_deck_note_types

分析卡片集以识别所有笔记类型（模型）及其字段定义。

参数：

  • deck_name (str)：要分析的 Anki 卡片集名称

返回值：卡片集中使用的所有唯一笔记类型及其字段名称

create_note

在指定的卡片集中创建新的笔记。

参数：

  • deck_name (str)：要添加笔记的 Anki 卡片集名称
  • model_name (str)：要使用的笔记类型/模型名称
  • fields (dict)：字段名称到值的映射字典（例如，{'Front': '问题', 'Back': '答案'}）
  • tags (list, 可选)：要添加到笔记的可选标签列表

返回值：包含 noteId 和成功状态或错误消息的 JSON 对象

update_note

更新现有笔记的特定字段，同时保留其他字段。

参数：

  • note_id (int)：要更新的笔记的 ID
  • fields (dict)：字段名称到新值的映射字典（例如，{'Audio': '[sound:发音.mp3]'}）
  • tags (list, 可选)：要替换现有标签的可选标签列表

返回值：包含成功状态和更新字段信息的 JSON 对象

用例：非常适合为现有的卡片添加音频文件或更新特定内容

create_deck_with_note_type

创建一个新的卡片集，并可选地创建一个带有自定义字段和模板的新笔记类型。

参数：

  • deck_name (str)：新 Anki 卡片集的名称
  • model_name (str)：笔记类型/模型的名称
  • fields (list)：字段名称列表（例如，['正面', '背面', '额外']）
  • card_templates (list, 可选)：可选的卡片模板定义列表

返回值：包含创建状态和详细信息的 JSON 对象

list_note_types

列出所有可用的笔记类型（模型）及其详细信息。

参数：无

返回值：关于所有笔记类型的详细信息，包括字段、模板和样式

generate_audio

使用 Google Cloud 文本转语音 API 和 Chirp 声音从文本生成高质量音频文件。

参数：

  • text (str)：要转换为语音的文本
  • language (str, 可选)：语言代码（默认："cmn-cn" 用于中文）
  • voice (str, 可选)：声音名称（默认："cmn-CN-Chirp3-HD-Achernar" 用于中文高清声音）

返回值：包含 base64 编码的 MP3 音频数据和元数据的 JSON 对象

设置：需要 GOOGLE_CLOUD_API_KEY 环境变量

特性：具有自然发音的高清声音，特别是对于中文学习非常出色

save_media_file

将 base64 编码的媒体数据保存为 Anki 媒体收藏中的文件，以便在卡片中使用。

参数：

  • filename (str)：要保存的文件名称（例如，'audio.mp3', 'image.jpg'）
  • base64_data (str)：base64 编码的文件数据
  • media_type (str, 可选)：媒体文件类型（默认："audio"）

返回值：包含保存的文件名和成功状态的 JSON 对象

用例：保存生成的音频或其他媒体文件以在 Anki 卡片中使用

generate_and_save_audio

从文本生成音频并将其直接保存到 Anki 的媒体收藏中，一次完成。

参数：

  • text (str)：要转换为语音并保存的文本
  • filename (str)：音频文件的名称（例如，'发音.mp3'）
  • language (str, 可选)：语言代码（默认："cmn-cn" 用于中文）
  • voice (str, 可选)：声音名称（默认："cmn-CN-Chirp3-HD-Achernar"）

返回值：包含文件名和用于卡片字段的 sound 标签的 JSON 对象

设置：需要 GOOGLE_CLOUD_API_KEY 环境变量

用例：一步生成和保存音频，返回 [sound:filename.mp3] 标签，准备用于卡片字段

create_notes_bulk

在一个批次操作中创建多个笔记，以实现最大效率。优雅地处理重复项，报告哪些笔记是重复项，同时仍创建非重复项。新功能：可选地为每个笔记自动生成音频文件使用 Google TTS。

参数：

  • deck_name (str)：要添加笔记的 Anki 卡片集名称

  • notes_list (list)：笔记字典列表，每个字典包含 'model_name', 'fields'，以及可选的 'tags'

  • auto_audio (AutoAudioConfig 或 null, 可选)：重要：作为下述结构所示的字典/对象传递，而不是 JSON 字符串。 自动音频生成配置：

    • enabled (bool, 必需)：必须为 true 才能启用音频生成
    • source_field (str, 必需)：要从中读取文本的字段名称（例如，"正面", "汉字"）
    • target_field (str, 必需)：要写入音频标签的字段名称（例如，"音频"）
    • language (str, 可选)：语言代码 - 默认为 "cmn-cn" 用于中文
    • voice (str, 可选)：声音名称 - 默认为 "cmn-CN-Chirp3-HD-Achernar"

    正确格式（字典对象）：

    {
  "enabled": true,
  "source_field": "汉字",
  "target_field": "音频",
  "language": "cmn-cn",
  "voice": "cmn-CN-Chirp3-HD-Achernar"
}

    错误 - 不要作为字符串传递：

    "{\"enabled\": true, \"source_field\": \"汉字\", ...}"  ❌ 错误

    要禁用音频生成，传递 null 或完全省略此参数。

返回值：包含成功/失败计数、成功笔记数组、失败笔记数组以及如果启用音频生成的结果的 JSON 对象

特性：

  • 使用 canAddNotesWithErrorDetail 预检查哪些笔记可以添加
  • 只尝试添加有效的笔记，确保没有批处理失败
  • 为每个失败的笔记提供详细的错误报告（重复项、验证错误等）
  • 返回成功创建的笔记的 noteIds 以供进一步处理
  • 为所有笔记一次性自动生成音频文件 - 不需要单独创建笔记然后再更新它们！
  • 音频生成报告每个笔记的成功/失败情况
  • 如果目标字段已有内容，则跳过音频生成

用例：一次性高效创建 20 张中文词汇卡片并附带音频，而不是分别创建卡片再逐一更新

update_notes_bulk

在一个批次操作中更新多个笔记，以实现最大效率。

参数：

  • updates (list)：更新字典列表，每个字典包含 'note_id', 'fields' 字典，以及可选的 'tags' 列表

返回值：包含成功/失败计数和详细更新结果的 JSON 对象

用例：非常适合批量更新，如一次性为多张卡片添加音频文件

find_similar_notes

查找包含搜索文本作为子字符串的任何字段中的笔记。简单而可靠的文本匹配。

参数：

  • deck_name (str)：要在其中搜索的 Anki 卡片集名称
  • search_text (str)：要在任何字段中搜索的子字符串
  • case_sensitive (bool, 可选)：搜索是否应区分大小写（默认：false）
  • max_results (int, 可选)：要返回的最大匹配笔记数（默认：2_0）

返回值：包含匹配笔记及其详细信息的 JSON 对象，显示哪些字段匹配了搜索条件

特性：

  • 跨所有笔记字段快速子字符串匹配
  • 区分大小写或不区分大小写的搜索选项
  • 显示确切哪些字段匹配了搜索条件
  • 不需要外部 API 依赖

技术细节

  • 框架：FastMCP（基于 FastAPI）
  • 服务器名称： "anki-mcp"
  • AnkiConnect URL：http://localhost:8765
  • 依赖项：fastapi, fastmcp, requests, uvicorn
  • 外部 API：
    • Google Cloud 文本转语音 API（用于音频生成）
  • 音频格式：MP3，带 base64 编码

特性

  • 高清音频生成：使用 Google Cloud Chirp 声音的优质 TTS，优化了中文发音
  • 自动批量音频生成：一次性创建带有音频的笔记 - 不需要先创建笔记再单独添加音频！
  • 笔记更新：更新现有笔记的新内容，如音频文件，同时保留其他字段
  • 媒体管理：直接集成到 Anki 的媒体收藏中，实现无缝文件处理
  • 批量操作：高效的批量笔记创建和更新，适用于大型数据集
  • 快速文本搜索：简单的子字符串匹配，用于查找包含特定文本的笔记
  • 全面错误处理：针对所有 API 失败和边缘情况的强大错误处理
  • 智能数据格式化：内容截断和格式化，以实现最佳可读性
  • 高效抽样：对大型数据集进行有效抽样，不会出现内存问题
  • 自定义模板：完全支持自定义卡片模板和 CSS 样式
  • 类型安全：使用 Pydantic 进行完整的参数验证
  • 安全的 API 密钥处理：基于环境变量的 API 密钥管理
  • 强大的错误处理：预验证笔记，并对重复项和其他问题提供详细的错误报告
  • 跨语言支持：优化了中文学习，但支持多种语言