Mousetail

🚀 最简单、最稳定的Anki MCP服务器

Mousetail旨在为Anki与大语言模型（LLM）的连接提供最简单、最可靠的方式。它无需任何插件，只需安装Anki和你想连接到牌组的LLM即可。

🚀 快速开始

启动服务器非常简单，只需运行以下命令：

uvx mousetail

如需查看与Claude Code、Claude Desktop和其他LLM工具集成的详细说明，请参考：

• 使用指南
• API参考

✨ 主要特性

• 极简：支持Anki的核心操作，包括创建、读取、更新和删除。
• 稳定：直接使用Anki稳定的pylib API，无需插件或依赖。
• 简单：无需配置，可自动发现你的Anki牌组。

📋 使用场景

• 选择性记忆：将与LLM对话中学到的内容有选择地存入记忆。

  "根据我们的对话创建一个牌组，以免我忘记关键细节"

• 与牌组交互：使用LLM与你的牌组进行交互。

  "创建一张卡片 - 什么是系数？创建一张卡片 - 识别这个多项式中的第一个系数"

• 清理牌组：使用LLM清理牌组。

  "检查我的法语词汇牌组的正确性，并纠正任何错误、拼写错误或失误"

🔄 同步功能

Mousetail支持将你的Anki牌组与AnkiWeb或自托管同步服务器进行同步，从而确保你的牌组在不同设备间保持一致。

快速开始

与AnkiWeb同步（保存凭证以便后续同步）：

> "保存我的AnkiWeb凭证：用户名是myuser@example.com，密码是mypassword"
> "将我的牌组与AnkiWeb同步"

凭证管理

Mousetail会将凭证安全地存储在系统的凭证管理器中：

• macOS：钥匙串
• Windows：凭证管理器
• Linux：秘密服务（如GNOME Keyring、KWallet等）

可用的凭证工具：

• save_sync_credentials：安全保存用户名/密码
• load_sync_credentials：加载已保存的凭证
• delete_sync_credentials：删除已保存的凭证

同步选项

sync_collection工具支持以下同步选项：

• AnkiWeb同步（默认）：不填写端点
• 自托管服务器：提供自定义端点URL（例如https://sync.example.com）
• 媒体同步：默认启用，包括图片和音频文件
• 仅同步牌组：设置sync_media: false以跳过媒体同步

示例

• 首次使用AnkiWeb设置：

> "保存我在AnkiWeb的同步凭证 - 用户名：user@example.com，密码：mypass123"
> "同步我的牌组"

• 使用自托管服务器：

> "保存我的同步凭证 - 用户名：john，密码：secret，端点：https://sync.myserver.com"
> "同步我的牌组"

• 一次性同步（不保存凭证）：

> "使用用户名user@example.com和密码mypass123将我的牌组与AnkiWeb同步"

• 仅同步牌组（跳过媒体）：

> "同步我的牌组，但不同步媒体文件"

配置

你可以在config.json中设置默认同步端点：

{
  "sync": {
    "endpoint": "https://sync.example.com"
  }
}

将endpoint设置为null以默认使用AnkiWeb。

重要提示

⚠️ 重要提示

• 先关闭Anki：如果Anki应用程序正在运行，同步将会失败。
• 媒体同步：媒体同步速度较慢且占用更多带宽，但可确保图片和音频文件同步。
• 冲突解决：如果发生冲突，请先从Anki桌面端进行同步以解决问题。
• 安全问题：凭证不会以明文形式存储，而是保存在系统的安全凭证存储中。

自托管同步服务器设置

若要与你自己的服务器进行同步，请按以下步骤操作：

1. 设置一个Anki同步服务器。
2. 在服务器上配置凭证（使用环境变量，如SYNC_USER1=user:password）。
3. 在Mousetail中保存带有服务器端点的凭证。
4. 正常进行同步。

有关同步服务器的详细设置，请参阅官方Anki文档。

📌 重要说明

牌组访问方式

MCP服务器会在标准位置查找Anki牌组：

• macOS：~/Library/Application Support/Anki2/[Profile]/collection.anki2
• Linux：~/.local/share/Anki2/[Profile]/collection.anki2
• Windows：%APPDATA%\Anki2\[Profile]\collection.anki2

你无需配置路径，服务器会自动发现可用的牌组，也可以通过配置进行自定义。

⚙️ 配置

可以通过config.json文件对服务器进行自定义配置。具体配置选项请参阅**使用指南**。

💻 开发

本地开发设置

若要在本地使用Claude Code开发和测试Mousetail，请按以下步骤操作：

1. 克隆仓库：

git clone https://github.com/listfold/mousetail.git
cd mousetail

2. 安装依赖：

uv sync

3. 配置Claude Code： 项目包含一个.mcp.json文件，用于为本地开发配置MCP服务器：

{
  "mcpServers": {
    "mousetail": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "mousetail.mcp.stdio_server"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

4. 重启Claude Code： 配置完成后，重启Claude Code以加载MCP服务器。
5. 验证服务器：

• 在Claude Code中使用/context查看可用的MCP工具。
• Mousetail服务器应显示所有可用工具（如list_collections、create_note、sync_collection等）。

6. 测试同步功能：

• 测试前关闭Anki桌面应用程序。
• 测试凭证管理：save_sync_credentials、load_sync_credentials、delete_sync_credentials。
• 使用你的AnkiWeb凭证或自托管服务器测试同步：sync_collection。

核心目标

开发Mousetail的原因是现有的所有MCP Anki工具都依赖于AnkiConnect插件。

AnkiConnect是Anki的一个HTTP服务器，最初用于支持将浏览器扩展（如yomichan）连接到Anki。对于MCP开发而言，它并非必需，且会带来一些问题：

• 增加复杂性：为Anki专门设置一个HTTP服务器会占用端口。
• 引入风险：如果AnkiConnect API发生更改或出现错误，MCP工具将无法正常工作。
• 增加额外步骤：所有现有的MCP工具都需要安装AnkiConnect插件。

Mousetail采用了更简单的方法，它直接与Anki的pylib集成。这是Anki核心的稳定API，不会随意或频繁更改，也无需任何第三方插件。

由于Mousetail注重简单性，因此它比其他工具更稳定。但需要注意的是，Mousetail不会与Anki UI集成，并且可以合理推测它仅适用于与同一系统上的LLM工具和Anki牌组一起使用。

构建文档

项目使用Sphinx和Furo主题从Python文档字符串生成文档。

1. 安装文档依赖：

uv pip install ".[docs]"

2. 构建文档：

uv run python -m sphinx -b html docs docs/_build/html

3. 查看文档： 在浏览器中打开docs/_build/html/index.html。

文档会在每次推送到主分支时自动构建并部署到GitHub Pages。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。