使用说明

Anki MCP 服务器

一个通过模型上下文协议（MCP）与Anki交互的FastMCP服务器。该服务器提供了全面的工具来管理Anki的卡片组、笔记和笔记类型，并具备高级功能，包括AI驱动的音频生成、批量操作和语义相似度搜索。

使用的外部API

该项目集成了多个外部API，以提供增强的功能：

谷歌云文本转语音API

目的使用谷歌Chirp语音技术，从文本生成高质量音频
用例为记忆卡片生成发音音频文件
特点/特性高清音质，发音自然，尤其适用于中文
设置需要 GOOGLE_CLOUD_API_KEY 环境变量

AnkiConnect API（本地）

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

设置

使用 uv 安装依赖项：
```
uv sync
```
确保Anki已安装AnkiConnect插件并正在运行：
- 在Anki中，前往工具 > 插件 > 获取插件
- 输入代码： 2055492159
- 重启Anki

（可选）为音频生成设置API密钥：

# For audio generation with Google Cloud TTS
export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

启动服务器：
```
uv run server.py
```

Claude 桌面集成

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

配置位置

macOS（发音为 /ˈmækOS/，中文可称为“麦奥斯”或直接使用原名“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"
      }
    }
  }
}

设置步骤

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

重要注意事项

确保 Anki正在运行 在使用工具之前，请安装AnkiConnect插件
这个（或：该） uv 该命令将自动处理Python环境和依赖项
确保 uv 已安装在您的系统上（curl -LsSf https://astral.sh/uv/install.sh | sh）

备选方案：使用环境变量

如果您希望在您的shell环境中保留您的API密钥，可以省略 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 Desktop，您应该会在对话中看到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 （字符串）：要分析的Anki牌组的名称

退货牌组中使用的所有唯一记号类型及其字段名称

`create_note`

在指定的牌组中创建一个新的笔记。

参数：

deck_name (str): 要添加卡片的Anki牌组的名称
model_name (字符串): 要使用的笔记类型/模型的名称
fields (字典): 将字段名映射到值的字典（例如。， {'Front': 'Question', 'Back': 'Answer'})
tags (列表，可选)：要添加到笔记中的可选标签列表

退货包含noteId和成功状态或错误信息的JSON对象

`update_note`

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

参数：

note_id (int): 要更新的笔记的ID
fields (字典): 字典，用于将字段名映射到新值（例如。， {'Audio': '[sound:pronunciation.mp3]'})
tags （列表，可选）：可选的标签列表，用于替换现有标签

退货包含成功状态和更新字段信息的JSON对象

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

`create_deck_with_note_type`

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

参数：

deck_name (str): 新Anki卡片组的名称
model_name (str): 笔记类型/模型的名称
fields (列表)：字段名称列表（例如。， ['Front', 'Back', 'Extra'])
card_templates （列表，可选）：可选的卡片模板定义列表

退货包含创建状态和详细信息的JSON对象

`list_note_types`

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

参数无

退货关于所有笔记类型的信息，包括字段、模板和样式

`generate_audio`

使用Google Cloud Text-to-Speech API和Chirp声音，从文本生成高质量音频文件。

参数：

text (str): 要转换为语音的文本
language (str, 可选): 语言代码（默认值：“cmn-cn”表示中文）
voice (字符串，可选)：语音名称（默认：对于中文高清语音，为“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 (字符串)：要转换为语音并保存的文本
filename (str): 音频文件的名称（例如，'pronunciation.mp3'）
language (str, 可选)：语言代码（默认：“cmn-cn”表示中文）
voice (str, 可选): 语音名称（默认: "cmn-CN-Chirp3-HD-Achernar"）

回报包含文件名和声音标签的JSON对象，用于卡片字段

设置需要 GOOGLE_CLOUD_API_KEY 环境变量

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

`create_notes_bulk`

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

参数：

deck_name （字符串）：要添加笔记的Anki牌组的名称
notes_list (列表): 一个包含笔记字典的列表，每个字典都包含 'model_name'（模型名称）、'fields'（字段），以及可选的 'tags'（标签）
auto_audio （AutoAudioConfig 或 null，可选）： 重要提示：请以字典/对象的形式传递，结构如下所示，而非以JSON字符串的形式。 自动音频生成配置：
- enabled (布尔值，必需)：必须为 true 以启用音频生成
- source_field (str, 必需): 要从中读取文本的字段名称（例如，“Front”，“Hanzi”）
- target_field (str, 必填): 要写入音频标签的字段名称（例如，“音频”）
- language (字符串，可选)：语言代码 - 默认为“cmn-cn”表示中文
- voice (字符串，可选)：语音名称 - 默认为 "cmn-CN-Chirp3-HD-Achernar"
正确的格式（字典对象）：
```
{
  "enabled": true,
  "source_field": "Hanzi",
  "target_field": "Audio",
  "language": "cmn-cn",
  "voice": "cmn-CN-Chirp3-HD-Achernar"
}
```
错误 - 不要作为字符串传递：
```
"{\"enabled\": true, \"source_field\": \"Hanzi\", ...}"  ❌ INCORRECT
```
要禁用音频生成，请传递 null 或者完全省略此参数。

退货包含成功/失败计数、成功笔记数组、失败笔记数组以及（如已启用）音频生成结果的JSON对象

特点/功能:

使用 canAddNotesWithErrorDetail 进行预检查，以确定可以添加哪些备注
仅尝试添加有效备注，确保无批次失败
为每条失败的笔记提供详细的错误报告（包括重复项、验证错误等）
返回成功创建的笔记的ID，以便后续处理
一键为所有音符自动生成音频文件 - 无需单独创建笔记然后再逐一更新！
音频生成报告对每个音符分别报告成功/失败
如果目标字段已有内容，则跳过音频生成

用例一次性高效创建20张带有音频的中文词汇卡片，无需先创建卡片再逐一更新

`update_notes_bulk`

在一个批处理操作中更新多个备注，以实现最大效率。

参数:

updates (列表): 更新字典的列表，每个字典包含 'note_id'（笔记ID）、'fields'（字段）字典，以及可选的 'tags'（标签）列表

退货包含成功/失败计数及详细更新结果的JSON对象

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

`find_similar_notes`

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

参数：

deck_name (str): 要搜索的Anki牌组的名称
search_text (字符串)：在任意字段中作为子字符串搜索的文本
case_sensitive (布尔值，可选)：搜索时是否区分大小写（默认：否）
max_results (int, 可选): 返回的最大匹配音符数量（默认：20）

退货包含匹配笔记和详细信息的JSON对象，其中说明了哪些字段包含搜索文本

特点/功能:

在所有笔记字段中快速进行子串匹配
区分大小写或不区分大小写的搜索选项
显示与搜索条件完全匹配的字段
无需外部API依赖

技术细节

框架FastMCP（基于FastAPI构建）
服务器名称“anki-mcp”
AnkiConnect URLhttp://localhost:8765 翻译为中文是：“本地主机的8765端口”
依赖项FastAPI, FastMCP, requests, Uvicorn
外部应用程序编程接口（APIs）：
- 谷歌云文本转语音API（用于音频生成）
音频格式带有base64编码的MP3文件

特点/功能

高清音频生成使用谷歌云Chirp语音的优质文本转语音（TTS）服务，针对中文发音进行优化
自动批量音频生成一键创建带音频的笔记——无需先创建笔记再单独添加音频！
笔记更新在保留其他字段的同时，用新内容（如音频文件）更新现有笔记
媒体管理与Anki的媒体库直接集成，实现无缝文件处理
批量操作高效批量创建和更新大型数据集中的备注
快速文本搜索简单的子字符串匹配，用于查找包含特定文本的笔记
全面的错误处理为所有API故障和边缘情况提供强大的错误处理
智能数据格式化内容截断和格式化以优化可读性
随机抽样高效采样大型数据集，无内存问题
自定义模板完全支持自定义卡片模板和CSS样式
类型安全使用 Pydantic 完成参数验证
安全处理API密钥基于环境变量的API密钥管理
强大的错误处理笔记的预验证，包含针对重复项及其他问题的详细错误报告
跨语言支持专为中文学习优化，但支持多种语言

使用说明

Anki MCP 服务器

使用的外部API

谷歌云文本转语音API

AnkiConnect API（本地）

设置

Claude 桌面集成

配置位置

配置示例

设置步骤

重要注意事项

备选方案：使用环境变量

验证

可用工具

list_decks

get_deck_notes

get_deck_sample

get_deck_note_types

create_note

update_note

create_deck_with_note_type

list_note_types

generate_audio

save_media_file

generate_and_save_audio

create_notes_bulk

update_notes_bulk

find_similar_notes

技术细节

特点/功能

相关 MCP

图表生成服务

Gmail自动化管理服务

ArcticDB 数据读写 MCP 服务

预算管理协议服务器

MIRO白板连接服务

项目任务批量管理服务