AI导哈

Anki MCP 服务器

一个为Anki提供模型上下文协议（MCP）的服务器，允许AI助手通过标准化接口程序化地创建、读取、更新和管理Anki闪卡。

  • by letuanvu08
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 letuanvu08/anki-mcp

使用说明

Anki MCP服务器

一个模型上下文协议（MCP）服务器，提供与Anki的无缝集成，使AI助手能够与您的闪卡收藏进行交互。通过标准化界面以编程方式创建、读取、更新和管理Anki卡。

特性

  • 🎴 卡片管理：使用全字段自定义创建、检索和更新抽认卡
  • 🔍 智能搜索：按ID、关键字、标签、套牌或任何Anki搜索语法查询卡片
  • 📊 审查集成：以编程方式访问到期卡、新卡和答题卡
  • 🎵 媒体支持：自动处理音频和图像（本地文件、URL或现有媒体）
  • 🔄 批量操作：在一次操作中高效创建多张卡
  • 🎯 通用工具：灵活的工具，适用于任何甲板、笔记类型和字段配置

先决条件

  1. Anki桌面应用程序 -必须在MCP服务器使用期间运行
  2. AnkiConnect附加组件 -从Anki安装：工具→ 附加组件→ 获取附加组件→ Code: 2055492159

⚠️ 重要：Anki必须在启用AnkiConnect的情况下运行，此MCP服务器才能运行。

资源

  • anki://search/deckcurrent -当前牌组中的所有牌
  • anki://search/isdue -卡片到期待审核
  • anki://search/isnew -新的看不见的卡片
  • 自定义查询： anki://search/tag:vocabulary, anki://search/deck:Spanish等等。

工具

  • update_card -更新卡片/笔记（答案、更新字段、更新标签）
  • add_card -使用自定义卡片组、模型和字段创建新的抽认卡
  • batch_add_card -一次创建多张抽认卡
  • get_due_cards -获取要审核的卡片列表
  • get_new_cards -获取新看不见的卡片列表
  • get_card -通过ID或查询检索详细的卡信息

发展

安装依赖项：

npm install

构建服务器：

npm run build

对于自动重建的开发：

npm run watch

媒体文件

如何处理媒体文件

当您添加带有图像或音频文件的卡时，服务器会自动处理不同类型的媒体源：

  1. 本地文件路径：如果您提供了计算机上文件的绝对路径（例如。， /Users/mycomputer/Documents/images/prune.jpg)，服务器将：

    • 从磁盘读取文件
    • 将其转换为base64
    • 使用以下方式将其上传到Anki的媒体收藏 storeMediaFile API
    • 按文件名在卡中引用它

  2. 网址：如果您提供URL（例如。， https://example.com/image.jpg)，Anki Connect将在创建卡时自动下载文件。

  3. 现有媒体：如果您只提供文件名（例如。， prune.jpg)，它假定该文件已存在于Anki的媒体文件夹中。

解决图像问题

如果图像在Anki中显示不正确：

  1. 检查文件路径：确保图像文件的路径正确并且文件存在
  2. 文件权限：确保应用程序可以读取该文件
  3. 支持的格式：Anki支持常见的图像格式（JPG、PNG、GIF、SVG、WebP）
  4. 文件大小：非常大的文件可能会导致问题
  5. 特殊字符：尽可能避免文件名中的特殊字符

服务器现在将自动处理本地文件路径，因此您不再需要手动将图像复制到Anki的媒体文件夹中。

安装和配置

安装

  1. 克隆或下载此存储库
  2. 安装依赖项：
    npm install
  3. 构建服务器：
    npm run build

使用Claude Desktop进行配置

将服务器配置添加到Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "anki-mcp-server": {
      "command": "/absolute/path/to/anki-mcp-server/build/index.js"
    }
  }
}

💡 小贴士：替换 /absolute/path/to/anki-mcp-server 包含克隆此存储库的实际完整路径。

与其他MCP客户端的配置

此服务器遵循标准MCP协议，可以与任何兼容MCP的客户端一起使用。将其配置为基于stdio的服务器，指向 build/index.js.

验证

配置后：

  1. 重新启动Claude Desktop（或您的MCP客户端）
  2. 确保Anki在安装了AnkiConnect的情况下运行
  3. 服务器应出现在可用的MCP服务器中
  4. 用一个简单的查询进行测试，比如“显示Anki的5张到期卡”

调试

由于MCP服务器通过stdio进行通信，调试可能具有挑战性。我们建议使用 MCP 检查员，可作为包脚本使用：

npm run inspector

检查器将提供一个URL，用于访问浏览器中的调试工具，您可以在其中：

  • 交互式测试工具调用
  • 查看请求/响应日志
  • 调试连接问题
  • 验证工具模式

故障排除

服务器未出现在Claude Desktop中：

  • 验证配置中的路径是绝对的（不是相对的）
  • 检查一下 build/index.js 存在（运行 npm run build)
  • 配置更改后重新启动Claude Desktop

“连接被拒绝”或超时错误：

  • 确保Anki正在运行
  • 验证AnkiConnect是否已安装（工具→ 附加组件）
  • 检查AnkiConnect设置是否允许本地主机连接（默认）

未更新/创建卡：

  • 如果您打开了Anki浏览器，请将其关闭（已知AnkiConnect限制）
  • 验证套牌和钞票类型名称是否完全匹配（区分大小写）
  • 检查字段名称是否与笔记类型的字段配置匹配

贡献

欢迎投稿！无论您是在修复错误、添加功能还是改进文档，我们都会感谢您的帮助。

如何做出贡献

  1. 分叉存储库 在GitHub上
  2. 克隆你的叉子 本地：
    git clone https://github.com/YOUR_USERNAME/anki-mcp.git
cd anki-mcp
  3. 创建新分支 对于您的功能或错误修复：
    git checkout -b feature/your-feature-name
  4. 进行更改 并进行彻底测试
  5. 构建和测试 您的更改：
    npm install
npm run build
npm run inspector  # Test with MCP Inspector
  6. 提交您的更改 带有清晰、描述性的信息：
    git commit -m "Add: description of your changes"
  7. 推你的叉子:
    git push origin feature/your-feature-name
  8. 打开拉取请求 在GitHub上清晰地描述您的更改

开发指南

  • 编写干净、可读的TypeScript代码
  • 遵循现有的代码样式和结构
  • 使用MCP检查器测试您的更改
  • 如果要添加新功能，请更新文档
  • 保持提交的重点和原子性

报告问题

发现错误或有功能请求？请在GitHub上打开一个问题：

  • 清晰、描述性的标题
  • 复制步骤（针对bug）
  • 预期行为与实际行为
  • 您的环境（操作系统、Anki版本、Node版本）

问题？

欢迎提出问题或加入现有问题的讨论。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

相关 MCP