Mousetail

🚀 The simplest and most stable MCP Server for Anki

Mousetail aims to provide the simplest and most reliable way to connect Anki to an LLM. It doesn't require any add - ons. All you need is Anki installed and an LLM you want to connect to your decks.

🚀 Quick Start

Running the server is as straightforward as:

uvx mousetail

For detailed instructions on integrating with Claude Code, Claude Desktop, and other LLM tools:

• Usage Guide
• API Reference

✨ Features

• Minimal: Supports core Anki operations, including create, read, update, and delete.
• Stable: Works directly with Anki's stable pylib API, without the need for add - ons or dependencies.
• Simple: No configuration is required. It automatically discovers your Anki collections.

💻 Usage Examples

Basic Usage

Selectively commit what you learn

You can selectively commit what you learn in a conversation with an LLM to memory. For example:

"Create a deck based on our conversation so I don't forget critical details"

Interact with your deck

Use an LLM to interact with your deck. For example:

"Create a card - what is a coefficient?, create a card - id the first coefficient in this polynomial"

Cleanup a deck

Use an LLM to clean up a deck. For example:

"Check my french vocab deck for correctness and correct any mistakes, typos or errors"

📚 Documentation

Syncing

Mousetail supports synchronizing your Anki collection with AnkiWeb or a self - hosted sync server, allowing you to keep your collection in sync across devices.

Quick Start

Sync with AnkiWeb (saves credentials for future syncs):

> "Save my AnkiWeb credentials: username is myuser@example.com and password is mypassword"
> "Sync my collection with AnkiWeb"

Credential Management

Mousetail stores credentials securely in your system's credential manager:

• macOS: Keychain
• Windows: Credential Manager
• Linux: Secret Service (GNOME Keyring, KWallet, etc.)

Available credential tools:

• save_sync_credentials: Save username/password securely.
• load_sync_credentials: Load saved credentials.
• delete_sync_credentials: Remove saved credentials.

Sync Options

The sync_collection tool supports:

• AnkiWeb sync (default): Leave the endpoint empty.
• Self - hosted servers: Provide a custom endpoint URL (e.g., https://sync.example.com).
• Media sync: Enabled by default, includes images and audio files.
• Collection - only sync: Set sync_media: false to skip media.

Examples

• First - time setup with AnkiWeb:

> "Save my sync credentials for AnkiWeb - username: user@example.com, password: mypass123"
> "Sync my collection"

• Using a self - hosted server:

> "Save my sync credentials - username: john, password: secret, endpoint: https://sync.myserver.com"
> "Sync my collection"

• One - time sync without saving credentials:

> "Sync my collection with AnkiWeb using username user@example.com and password mypass123"

• Collection - only sync (skip media):

> "Sync my collection but don't sync media files"

Configuration

You can set a default sync endpoint in config.json:

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

Leave endpoint as null to use AnkiWeb by default.

Important Notes

• Close Anki first: Sync will fail if the Anki application is running.
• Media sync: Media sync is slower and uses more bandwidth but ensures images/audio are synced.
• Conflicts: If conflicts occur, try syncing from Anki desktop first to resolve them.
• Security: Credentials are never stored in plain text; they're kept in your system's secure credential storage.

Self - Hosted Sync Server Setup

To sync with your own server:

1. Set up an Anki sync server.
2. Configure credentials on the server (using environment variables like SYNC_USER1=user:password).
3. Save your credentials in Mousetail with the server endpoint.
4. Sync normally.

For detailed sync server setup, see the official Anki documentation.

How Collections Are Accessed

The MCP server finds Anki collections at their standard locations:

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

You don't need to configure paths; the server automatically discovers available collections, and this can be customized using configuration.

Configuration

The server can be customized through a config.json file. See the Usage Guide for configuration options.

Development

Local Development Setup

To develop and test Mousetail locally with Claude Code:

1. Clone the repository:

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

2. Install dependencies:

   uv sync
   

3. Configure Claude Code: The project includes a .mcp.json file that configures the MCP server for local development:

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

4. Restart Claude Code: After the configuration is in place, restart Claude Code to load the MCP server.
5. Verify the server:
   • Use /context in Claude Code to see available MCP tools.
   • The mousetail server should appear with all available tools (list_collections, create_note, sync_collection, etc.).
6. Testing sync functionality:
   • Close the Anki desktop application before testing.
   • Test credential management: save_sync_credentials, load_sync_credentials, delete_sync_credentials.
   • Test sync: sync_collection with your AnkiWeb credentials or self - hosted server.

Core goals

Mousetail was developed because all existing MCP Anki tools depend on the AnkiConnect add - on.

AnkiConnect is a HTTP server for Anki, originally created to support connecting browser extensions like yomichan to Anki. For MCP development, it is unnecessary and introduces issues:

• Complexity: A dedicated HTTP server for Anki occupies a port.
• Risk: If the AnkiConnect API changes or has a bug, the MCP tool will break.
• Extra step: All current MCP tools require installing the AnkiConnect add - on.

Mousetail takes a much simpler approach. It integrates directly with Anki's pylib, a stable API that is part of Anki's core. Therefore, it is not subject to arbitrary or frequent changes and does not require any third - party add - ons.

Because it prioritizes simplicity, Mousetail will remain more stable than the alternatives. The trade - off is that Mousetail will never integrate with the Anki UI. It is also reasonable to assume that Mousetail will only work with colocated (same system) LLM tools and Anki decks.

Building Documentation

The project uses Sphinx with the Furo theme to generate documentation from Python docstrings.

1. Install documentation dependencies:

   uv pip install ".[docs]"
   

2. Build the documentation:

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

3. View the documentation: Open docs/_build/html/index.html in your browser.

The documentation is automatically built and deployed to GitHub Pages on every push to the main branch.

📄 License

This project is under the MIT License. See the LICENSE file for details.