MCP Tools¶

Tool implementations for each MCP operation exposed by the server.

Tool implementations for MCP server.

This module contains the actual implementation of each MCP tool exposed by the Anki MCP server. Each function corresponds to a tool that LLMs can call to interact with Anki collections.

async mousetail.mcp.tools.list_collections_tool()[source]¶

List all available Anki collections.

Scans the system for Anki profile directories and returns information about all discovered collections.

Return type:: dict
Returns:: Dict with ‘collections’ (list of collection info) and ‘count’ (int).

async mousetail.mcp.tools.get_collection_info_tool(collection_path=None)[source]¶

Get information about a collection.

Parameters:: collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.
Return type:: dict
Returns:: Dict with ‘success’ (bool), ‘collection’ (info dict) or ‘error’ (str).

async mousetail.mcp.tools.list_decks_tool(collection_path=None)[source]¶

List all decks in the collection.

Parameters:: collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.
Return type:: dict
Returns:: Dict with ‘success’ (bool), ‘decks’ (list), ‘count’ (int) or ‘error’ (str).

async mousetail.mcp.tools.create_deck_tool(deck_name, collection_path=None)[source]¶

Create a new deck.

Parameters:

deck_name (str) – Name for the new deck.
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘message’ (str), ‘deck_id’ (int) or ‘error’ (str).

async mousetail.mcp.tools.list_note_types_tool(collection_path=None)[source]¶

List all note types in the collection.

Parameters:: collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.
Return type:: dict
Returns:: Dict with ‘success’ (bool), ‘note_types’ (list with id, name, fields), ‘count’ (int) or ‘error’ (str).

async mousetail.mcp.tools.create_note_tool(deck_name, note_type_name, fields, tags=None, collection_path=None)[source]¶

Create a new note (flashcard).

Parameters:

deck_name (str) – Name of the deck where the note will be added.
note_type_name (str) – Name of the note type (e.g., ‘Basic’, ‘Cloze’).
fields (dict[str, str]) – Dictionary mapping field names to values (e.g., {‘Front’: ‘Question’, ‘Back’: ‘Answer’}).
tags (list[str]) – Optional list of tags to add to the note.
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘message’ (str), ‘note_id’ (int), ‘card_count’ (int) or ‘error’ (str).

async mousetail.mcp.tools.search_notes_tool(query, limit=100, collection_path=None)[source]¶

Search for notes using Anki search syntax.

Parameters:

query (str) – Anki search query (e.g., ‘deck:MyDeck’, ‘tag:important’, ‘front:python’).
limit (int) – Maximum number of results to return. Default is 100.
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘note_ids’ (list), ‘count’ (int), ‘query’ (str) or ‘error’ (str).

async mousetail.mcp.tools.get_note_tool(note_id, collection_path=None)[source]¶

Get detailed information about a specific note.

Parameters:

note_id (int) – ID of the note to retrieve.
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘note’ (dict with id, fields, tags, etc.) or ‘error’ (str).

async mousetail.mcp.tools.update_note_tool(note_id, fields=None, tags=None, collection_path=None)[source]¶

Update an existing note’s fields and/or tags.

Parameters:

note_id (int) – ID of the note to update.
fields (Optional[dict[str, str]]) – Optional dictionary mapping field names to new values.
tags (Optional[list[str]]) – Optional list of tags (replaces all existing tags).
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘message’ (str) or ‘error’ (str).

async mousetail.mcp.tools.save_sync_credentials_tool(username, password, endpoint=None)[source]¶

Save sync credentials securely to system keychain.

Stores credentials using the system’s secure credential storage: - macOS: Keychain - Windows: Credential Manager - Linux: Secret Service (GNOME Keyring, KWallet, etc.)

Parameters:

username (str) – AnkiWeb ID or sync server username.
password (str) – Account password.
endpoint (Optional[str]) – Optional sync server URL (saved separately). Leave empty for AnkiWeb.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘message’ (str) or ‘error’ (str).

async mousetail.mcp.tools.load_sync_credentials_tool()[source]¶

Load saved sync credentials from system keychain.

Return type:: dict
Returns:: Dict with ‘success’ (bool), ‘username’ (str), ‘password’ (str), ‘endpoint’ (str or None), or ‘error’ (str).

async mousetail.mcp.tools.delete_sync_credentials_tool()[source]¶

Delete saved sync credentials from system keychain.

Return type:: dict
Returns:: Dict with ‘success’ (bool), ‘message’ (str) or ‘error’ (str).

async mousetail.mcp.tools.sync_collection_tool(username=None, password=None, endpoint=None, sync_media=True, collection_path=None)[source]¶

Synchronize Anki collection with AnkiWeb or a self-hosted sync server.

This tool uploads local changes and downloads remote changes to keep your collection in sync. By default, it syncs both the collection data (cards, notes, decks) and media files (images, audio).

Authentication priority: 1. Credentials passed as parameters 2. Saved credentials from keychain 3. Error if no credentials available

Endpoint priority: 1. Endpoint parameter (if provided) 2. Saved endpoint from keychain 3. Endpoint from config.json 4. AnkiWeb (default)

Parameters:

username (Optional[str]) – AnkiWeb ID or sync server username (optional if saved).
password (Optional[str]) – Account password (optional if saved).
endpoint (Optional[str]) – Sync server URL (optional). Examples: - None or empty: Use AnkiWeb (default) - “https://sync.example.com”: Use self-hosted server
sync_media (bool) – Include media files in sync (default: True).
collection_path (Optional[str]) – Path to collection file (optional, uses default if not provided).

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘message’ (str), ‘required’ (str) or ‘error’ (str).

Tool Functions¶

Collection Tools¶

async mousetail.mcp.tools.list_collections_tool()[source]

List all available Anki collections.

Scans the system for Anki profile directories and returns information about all discovered collections.

Return type:: dict
Returns:: Dict with ‘collections’ (list of collection info) and ‘count’ (int).

async mousetail.mcp.tools.get_collection_info_tool(collection_path=None)[source]

Get information about a collection.

Parameters:: collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.
Return type:: dict
Returns:: Dict with ‘success’ (bool), ‘collection’ (info dict) or ‘error’ (str).

Deck Tools¶

async mousetail.mcp.tools.list_decks_tool(collection_path=None)[source]

List all decks in the collection.

Parameters:: collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.
Return type:: dict
Returns:: Dict with ‘success’ (bool), ‘decks’ (list), ‘count’ (int) or ‘error’ (str).

async mousetail.mcp.tools.create_deck_tool(deck_name, collection_path=None)[source]

Create a new deck.

Parameters:

deck_name (str) – Name for the new deck.
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘message’ (str), ‘deck_id’ (int) or ‘error’ (str).

Note Type Tools¶

async mousetail.mcp.tools.list_note_types_tool(collection_path=None)[source]

List all note types in the collection.

Parameters:: collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.
Return type:: dict
Returns:: Dict with ‘success’ (bool), ‘note_types’ (list with id, name, fields), ‘count’ (int) or ‘error’ (str).

Note Tools¶

async mousetail.mcp.tools.create_note_tool(deck_name, note_type_name, fields, tags=None, collection_path=None)[source]

Create a new note (flashcard).

Parameters:

deck_name (str) – Name of the deck where the note will be added.
note_type_name (str) – Name of the note type (e.g., ‘Basic’, ‘Cloze’).
fields (dict[str, str]) – Dictionary mapping field names to values (e.g., {‘Front’: ‘Question’, ‘Back’: ‘Answer’}).
tags (list[str]) – Optional list of tags to add to the note.
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘message’ (str), ‘note_id’ (int), ‘card_count’ (int) or ‘error’ (str).

async mousetail.mcp.tools.search_notes_tool(query, limit=100, collection_path=None)[source]

Search for notes using Anki search syntax.

Parameters:

query (str) – Anki search query (e.g., ‘deck:MyDeck’, ‘tag:important’, ‘front:python’).
limit (int) – Maximum number of results to return. Default is 100.
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘note_ids’ (list), ‘count’ (int), ‘query’ (str) or ‘error’ (str).

async mousetail.mcp.tools.get_note_tool(note_id, collection_path=None)[source]

Get detailed information about a specific note.

Parameters:

note_id (int) – ID of the note to retrieve.
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘note’ (dict with id, fields, tags, etc.) or ‘error’ (str).

async mousetail.mcp.tools.update_note_tool(note_id, fields=None, tags=None, collection_path=None)[source]

Update an existing note’s fields and/or tags.

Parameters:

note_id (int) – ID of the note to update.
fields (Optional[dict[str, str]]) – Optional dictionary mapping field names to new values.
tags (Optional[list[str]]) – Optional list of tags (replaces all existing tags).
collection_path (Optional[str]) – Path to the collection file. If None, uses the default collection.

Return type:

dict

Returns:

Dict with ‘success’ (bool), ‘message’ (str) or ‘error’ (str).