Yanki MCP Server ( Yet Another Anki MCP Server )

Yanki MCP Server（又一个 Anki MCP Server）

一个 Model Context Protocol 服务实现，可连接到本地运行的 Anki，提供卡片复习和创建功能。此项目是 scorzeth/anki-mcp-server 的分支版本，增加了按日期组织的功能。

可作为 npm 包使用：yanki-mcp-server

此服务旨在与 Anki 桌面应用和 Anki-Connect 插件配合使用。

使用前请确保已安装该插件。

资源

• anki://search/deckcurrent
  • 返回当前牌组中的所有卡片
  • 等同于 Anki 中的 deck:current
• anki://search/isdue
  • 返回等待学习的复习和学习中的卡片
  • 等同于 Anki 中的 is:due
• anki://search/isnew
  • 返回所有未见过的卡片
  • 等同于 Anki 中的 is:new

工具

• update_cards

  • 将指定卡片 ID 的卡片标记为已作答，并为其设置 1（重来）到 4（简单）的难度评分
  • 输入：
    • answers（数组）：包含对象的数组，对象包含 cardId（数字）和 ease（数字）字段

• add_card

  • 在按日期组织的牌组中创建新卡片（格式：DECK::YYYY::MM::DD）
  • 输入：
    • front（字符串）：卡片正面
    • back（字符串）：卡片背面

• get_due_cards

  • 返回当前到期复习的 n 张卡片
  • 输入：
    • num（数字）：卡片数量

• get_new_cards

  • 返回 n 张新卡片
  • 输入：
    • num（数字）：卡片数量

安装与使用

无需安装即可通过 npx 使用此包：

npx yanki-mcp-server

也可以全局安装：

npm install -g yanki-mcp-server
yanki-server

开发

克隆代码仓库并安装依赖：

git clone https://github.com/htlin222/yanki-mcp-server.git
cd yanki-mcp-server
npm install

构建服务：

npm run build

在开发过程中启用自动重新构建：

npm run watch

在开发过程中直接运行服务：

npm run dev

配置

要在 Claude Desktop 中使用，请添加服务配置：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "yanki-mcp-server": {
      "command": "npx",
      "args": ["yanki-mcp-server"],
      "env": {
        "DECK": "Default"
      }
    }
  }
}

调试

由于 MCP 服务通过 stdio 通信，调试可能会比较困难。我们建议使用 MCP Inspector，它可通过包脚本运行：

npm run inspector

Inspector 会提供一个 URL，可在浏览器中访问调试工具。

按日期组织卡片

此服务会自动按日期结构组织新卡片，而不是采用传统的按主题组织方式。创建新卡片时，卡片会添加到以下格式的牌组中：

DECK::YYYY::MM::DD

其中：

• DECK 是基础牌组名称（默认值为 "00_Inbox"，也可通过环境变量配置）
• YYYY 是 4 位年份
• MM 是 2 位月份
• DD 是 2 位日期

按日期组织的优势

1. 轻松整理：卡片会按创建日期自动整理，无需手动分类
2. 时间背景：复习特定时间段内创建的卡片（例如，在课程或项目期间）
3. 自然的间隔重复：卡片会自然地按你学习概念的时间分组
4. 节省时间：无需花时间决定每张卡片属于哪个类别
5. 历史记录：查看自己的学习历程

配置

你可以在 MCP 服务配置中设置 DECK 环境变量，自定义基础牌组名称：

"env": {
  "DECK": "YourCustomDeckName"
}

如果未指定，默认值为 "00_Inbox"。

更新日志

1.0.5 (2025-05-31)

• 完全移除所有控制台输出和日志记录功能
• 通过移除所有非必要输出简化代码库
• 确保 MCP 协议通信完全干净，没有多余输出
• 移除所有与日志记录相关的文件系统操作

1.0.4 (2025-05-31)

• 修复日志目录路径被创建在文件系统根目录的严重问题
• 改进日志系统，加入稳健的错误处理和回退机制
• 确保日志始终相对于当前工作目录创建
• 为日志记录添加静默失败机制，防止日志记录失败时破坏 MCP 协议

1.0.3 (2025-05-31)

• 通过将所有控制台输出重定向到日志文件，修复 MCP 通信协议问题
• 添加基于文件的日志记录系统，以保留所有调试和状态信息
• 日志存储在 logs 目录中，文件名按日期命名
• 确保 stdout 通信干净，以符合 MCP JSON-RPC 协议规范