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文件。