Mousetail

🚀 最もシンプルで安定したAnki用MCPサーバー

このプロジェクトは、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: Keychain
• Windows: Credential Manager
• Linux: Secret Service (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"
> "私のコレクションを同期してください"

資格情報を保存せずに一度だけ同期する場合：

> "AnkiWebと私のコレクションを同期してください。ユーザー名はuser@example.com、パスワードはmypass123です"

コレクションのみの同期（メディアをスキップする）：

> "私のコレクションを同期してくださいが、メディアファイルは同期しないでください"

設定

config.jsonファイルを使用して、サーバーをカスタマイズすることができます。設定オプションについては、使用ガイド を参照してください。

重要な注意事項

コレクションのアクセス方法

MCPサーバーは、Ankiのコレクションを標準の場所で見つけます。

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

パスを設定する必要はありません - サーバーが自動的に利用可能なコレクションを検出します。これは設定を使用してカスタマイズすることができます。

開発

ローカル開発のセットアップ

Claude CodeでMousetailをローカルで開発およびテストするには、以下の手順を実行します。

1. リポジトリをクローンする：

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

2. 依存関係をインストールする：

   uv sync
   

3. Claude Codeを設定する： プロジェクトには、ローカル開発用にMCPサーバーを設定する.mcp.jsonファイルが含まれています。

   {
     "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
   • 同期をテストする：sync_collectionを使用して、AnkiWebの資格情報または自前のサーバーで同期します。

核心的な目標

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とは統合されません。また、Mousetailは同じシステム上の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を開きます。

ドキュメントは、mainブランチにプッシュするたびに自動的にビルドされ、GitHub Pagesにデプロイされます。

📄 ライセンス

MITライセンス - 詳細については、LICENSEファイルを参照してください。