Anki MCP Server

A FastMCP server for interacting with Anki through the Model Context Protocol (MCP). This server provides comprehensive tools for managing Anki decks, notes, and note types, with advanced features including AI-powered audio generation, bulk operations, and semantic similarity search.

External APIs Used

This project integrates with several external APIs to provide enhanced functionality:

Google Cloud Text-to-Speech API

Purpose: High-quality audio generation from text using Google's Chirp voices
Use Case: Generate pronunciation audio files for flashcards
Features: HD quality voices with natural pronunciation, especially excellent for Chinese
Setup: Requires GOOGLE_CLOUD_API_KEY environment variable

AnkiConnect API (Local)

Purpose: Interface with Anki desktop application
Use Case: All Anki operations (create/read/update notes, manage decks, etc.)
Features: Complete Anki functionality via HTTP API
Setup: AnkiConnect add-on must be installed and Anki must be running

Setup

Install dependencies using uv:
```
uv sync
```
Make sure Anki is running with the AnkiConnect add-on installed:
- In Anki, go to Tools > Add-ons > Get Add-ons
- Enter code: 2055492159
- Restart Anki

(Optional) Set up API key for audio generation:

# For audio generation with Google Cloud TTS
export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

Run the server:
```
uv run server.py
```

Claude Desktop Integration

To use this MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json file:

Configuration Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration Example

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ],
      "env": {
        "GOOGLE_CLOUD_API_KEY": "your-google-cloud-api-key-here"
      }
    }
  }
}

Setup Steps

Ensure dependencies are installed: Make sure you've run uv sync in your anki-mcp directory
Find your config file at the location above (create it if it doesn't exist)
Update the path: Replace /path/to/your/anki-mcp/ with the actual path to your anki-mcp directory
Add your API key:
- Replace your-google-cloud-api-key-here with your actual Google Cloud API key (for audio generation)
Restart Claude Desktop for the changes to take effect

Important Notes

Make sure Anki is running with the AnkiConnect add-on before using the tools
The uv command will automatically handle the Python environment and dependencies
Make sure uv is installed on your system (curl -LsSf https://astral.sh/uv/install.sh | sh)

Alternative: Using Environment Variables

If you prefer to keep your API key in your shell environment, you can omit the env section:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ]
    }
  }
}

Then set the environment variable in your shell:

export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

Verification

Once configured, restart Claude Desktop and you should see the Anki MCP tools available in your conversations. You can verify by asking Claude to list your Anki decks or try any of the available tools.

Available Tools

`list_decks`

Lists all available Anki decks with count.

Parameters: None

Returns: Formatted string with all deck names and total count

`get_deck_notes`

Retrieves all notes/cards from a specific deck with detailed information.

Parameters:

deck_name (str): Name of the Anki deck to retrieve notes from

Returns: Detailed information about all notes including model name, tags, and field values

`get_deck_sample`

Gets a random sample of notes from a deck to understand typical note structure.

Parameters:

deck_name (str): Name of the Anki deck to sample notes from
sample_size (int, optional): Number of notes to sample (1-50, default: 5)

Returns: Detailed information about sampled notes

`get_deck_note_types`

Analyzes a deck to identify all note types (models) and their field definitions.

Parameters:

deck_name (str): Name of the Anki deck to analyze

Returns: All unique note types used in the deck with their field names

`create_note`

Creates a new note in the specified deck.

Parameters:

deck_name (str): Name of the Anki deck to add the note to
model_name (str): Name of the note type/model to use
fields (dict): Dictionary mapping field names to values (e.g., {'Front': 'Question', 'Back': 'Answer'})
tags (list, optional): Optional list of tags to add to the note

Returns: JSON object with noteId and success status or error message

`update_note`

Updates specific fields of an existing note while preserving other fields.

Parameters:

note_id (int): ID of the note to update
fields (dict): Dictionary mapping field names to new values (e.g., {'Audio': '[sound:pronunciation.mp3]'})
tags (list, optional): Optional list of tags to replace existing tags

Returns: JSON object with success status and updated field information

Use Case: Perfect for adding audio files to existing cards or updating specific content

`create_deck_with_note_type`

Creates a new deck and optionally a new note type with custom fields and templates.

Parameters:

deck_name (str): Name for the new Anki deck
model_name (str): Name for the note type/model
fields (list): List of field names (e.g., ['Front', 'Back', 'Extra'])
card_templates (list, optional): Optional list of card template definitions

Returns: JSON object with creation status and details

`list_note_types`

Lists all available note types (models) with comprehensive information.

Parameters: None

Returns: Information about all note types including fields, templates, and styling

`generate_audio`

Generates high-quality audio files from text using Google Cloud Text-to-Speech API with Chirp voices.

Parameters:

text (str): Text to convert to speech
language (str, optional): Language code (default: "cmn-cn" for Chinese)
voice (str, optional): Voice name (default: "cmn-CN-Chirp3-HD-Achernar" for Chinese HD voice)

Returns: JSON object with base64-encoded MP3 audio data and metadata

Setup: Requires GOOGLE_CLOUD_API_KEY environment variable

Features: HD quality voices with natural pronunciation, especially excellent for Chinese language learning

`save_media_file`

Saves base64 encoded media data as a file in Anki's media collection for use in cards.

Parameters:

filename (str): Name of the file to save (e.g., 'audio.mp3', 'image.jpg')
base64_data (str): Base64 encoded file data
media_type (str, optional): Type of media file (default: "audio")

Returns: JSON object with saved filename and success status

Use Case: Save generated audio or other media files for use in Anki cards

`generate_and_save_audio`

Generates audio from text and saves it directly to Anki's media collection in one operation.

Parameters:

text (str): Text to convert to speech and save
filename (str): Name for the audio file (e.g., 'pronunciation.mp3')
language (str, optional): Language code (default: "cmn-cn" for Chinese)
voice (str, optional): Voice name (default: "cmn-CN-Chirp3-HD-Achernar")

Returns: JSON object with filename and sound tag for use in card fields

Setup: Requires GOOGLE_CLOUD_API_KEY environment variable

Use Case: One-step audio generation and saving, returns [sound:filename.mp3] tag ready for card fields

`create_notes_bulk`

Creates multiple notes in a single batch operation for maximum efficiency. Handles duplicates gracefully by reporting which notes are duplicates while still creating non-duplicate notes. NEW: Optionally auto-generates audio files using Google TTS for each note.

Parameters:

deck_name (str): Name of the Anki deck to add notes to
notes_list (list): List of note dictionaries, each containing 'model_name', 'fields', and optionally 'tags'
auto_audio (AutoAudioConfig or null, optional): IMPORTANT: Pass as a dictionary/object with the structure shown below, NOT as a JSON string. Configuration for automatic audio generation:
- enabled (bool, required): Must be true to enable audio generation
- source_field (str, required): Name of field to read text from (e.g., "Front", "Hanzi")
- target_field (str, required): Name of field to write audio tag to (e.g., "Audio")
- language (str, optional): Language code - defaults to "cmn-cn" for Chinese
- voice (str, optional): Voice name - defaults to "cmn-CN-Chirp3-HD-Achernar"
Correct format (dictionary object):
```
{
  "enabled": true,
  "source_field": "Hanzi",
  "target_field": "Audio",
  "language": "cmn-cn",
  "voice": "cmn-CN-Chirp3-HD-Achernar"
}
```
WRONG - Do NOT pass as a string:
```
"{\"enabled\": true, \"source_field\": \"Hanzi\", ...}"  ❌ INCORRECT
```
To disable audio generation, pass null or omit this parameter entirely.

Returns: JSON object with success/failed counts, successful notes array, failed notes array, and audio generation results if enabled

Features:

Uses canAddNotesWithErrorDetail to pre-check which notes can be added
Only attempts to add valid notes, ensuring no batch failures
Provides detailed error reporting for each failed note (duplicates, validation errors, etc.)
Returns note IDs for successfully created notes for further processing
Auto-generates audio files for all notes in a single operation - no need to create notes and then update them separately!
Audio generation reports success/failure for each note individually
Skips audio generation if target field already has content

Use Case: Create 20 Chinese vocabulary cards with audio in one efficient operation instead of creating cards and then updating each one individually

`update_notes_bulk`

Updates multiple notes in a single batch operation for maximum efficiency.

Parameters:

updates (list): List of update dictionaries, each containing 'note_id', 'fields' dict, and optionally 'tags' list

Returns: JSON object with success/failure counts and detailed update results

Use Case: Perfect for batch updates like adding audio files to multiple cards at once

`find_similar_notes`

Finds notes that contain the search text as a substring in any field. Simple and reliable text matching.

Parameters:

deck_name (str): Name of the Anki deck to search in
search_text (str): Text to search for as a substring in any field
case_sensitive (bool, optional): Whether the search should be case sensitive (default: false)
max_results (int, optional): Maximum number of matching notes to return (default: 20)

Returns: JSON object with matching notes and details about which fields contained the search text

Features:

Fast substring matching across all note fields
Case-sensitive or case-insensitive search options
Shows exactly which fields matched the search criteria
No external API dependencies required

Technical Details

Framework: FastMCP (built on FastAPI)
Server Name: "anki-mcp"
AnkiConnect URL: http://localhost:8765
Dependencies: fastapi, fastmcp, requests, uvicorn
External APIs:
- Google Cloud Text-to-Speech API (for audio generation)
Audio Format: MP3 with base64 encoding

Features

HD Audio Generation: Premium quality TTS using Google Cloud Chirp voices, optimized for Chinese pronunciation
Automatic Bulk Audio Generation: Create notes with audio in one operation - no need to create notes and then add audio separately!
Note Updates: Update existing notes with new content like audio files while preserving other fields
Media Management: Direct integration with Anki's media collection for seamless file handling
Bulk Operations: Efficient batch note creation and updates for large datasets
Fast Text Search: Simple substring matching for finding notes containing specific text
Comprehensive Error Handling: Robust error handling for all API failures and edge cases
Smart Data Formatting: Content truncation and formatting for optimal readability
Random Sampling: Efficient sampling for large datasets without memory issues
Custom Templates: Full support for custom card templates and CSS styling
Type Safety: Complete parameter validation using Pydantic
Secure API Key Handling: Environment variable-based API key management
Robust Error Handling: Pre-validation of notes with detailed error reporting for duplicates and other issues
Cross-Language Support: Optimized for Chinese language learning but supports multiple languages

Anki MCP Server

External APIs Used

This project integrates with several external APIs to provide enhanced functionality:

Google Cloud Text-to-Speech API

Purpose: High-quality audio generation from text using Google's Chirp voices
Use Case: Generate pronunciation audio files for flashcards
Features: HD quality voices with natural pronunciation, especially excellent for Chinese
Setup: Requires GOOGLE_CLOUD_API_KEY environment variable

AnkiConnect API (Local)

Purpose: Interface with Anki desktop application
Use Case: All Anki operations (create/read/update notes, manage decks, etc.)
Features: Complete Anki functionality via HTTP API
Setup: AnkiConnect add-on must be installed and Anki must be running

Setup

Install dependencies using uv:
```
uv sync
```
Make sure Anki is running with the AnkiConnect add-on installed:
- In Anki, go to Tools > Add-ons > Get Add-ons
- Enter code: 2055492159
- Restart Anki

(Optional) Set up API key for audio generation:

# For audio generation with Google Cloud TTS
export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

Run the server:
```
uv run server.py
```

Claude Desktop Integration

To use this MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json file:

Configuration Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration Example

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ],
      "env": {
        "GOOGLE_CLOUD_API_KEY": "your-google-cloud-api-key-here"
      }
    }
  }
}

Setup Steps

Ensure dependencies are installed: Make sure you've run uv sync in your anki-mcp directory
Find your config file at the location above (create it if it doesn't exist)
Update the path: Replace /path/to/your/anki-mcp/ with the actual path to your anki-mcp directory
Add your API key:
- Replace your-google-cloud-api-key-here with your actual Google Cloud API key (for audio generation)
Restart Claude Desktop for the changes to take effect

Important Notes

Make sure Anki is running with the AnkiConnect add-on before using the tools
The uv command will automatically handle the Python environment and dependencies
Make sure uv is installed on your system (curl -LsSf https://astral.sh/uv/install.sh | sh)

Alternative: Using Environment Variables

If you prefer to keep your API key in your shell environment, you can omit the env section:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ]
    }
  }
}

Then set the environment variable in your shell:

export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

Verification

Available Tools

`list_decks`

Lists all available Anki decks with count.

Parameters: None

Returns: Formatted string with all deck names and total count

`get_deck_notes`

Retrieves all notes/cards from a specific deck with detailed information.

Parameters:

deck_name (str): Name of the Anki deck to retrieve notes from

Returns: Detailed information about all notes including model name, tags, and field values

`get_deck_sample`

Gets a random sample of notes from a deck to understand typical note structure.

Parameters:

deck_name (str): Name of the Anki deck to sample notes from
sample_size (int, optional): Number of notes to sample (1-50, default: 5)

Returns: Detailed information about sampled notes

`get_deck_note_types`

Analyzes a deck to identify all note types (models) and their field definitions.

Parameters:

deck_name (str): Name of the Anki deck to analyze

Returns: All unique note types used in the deck with their field names

`create_note`

Creates a new note in the specified deck.

Parameters:

deck_name (str): Name of the Anki deck to add the note to
model_name (str): Name of the note type/model to use
fields (dict): Dictionary mapping field names to values (e.g., {'Front': 'Question', 'Back': 'Answer'})
tags (list, optional): Optional list of tags to add to the note

Returns: JSON object with noteId and success status or error message

`update_note`

Updates specific fields of an existing note while preserving other fields.

Parameters:

note_id (int): ID of the note to update
fields (dict): Dictionary mapping field names to new values (e.g., {'Audio': '[sound:pronunciation.mp3]'})
tags (list, optional): Optional list of tags to replace existing tags

Returns: JSON object with success status and updated field information

Use Case: Perfect for adding audio files to existing cards or updating specific content

`create_deck_with_note_type`

Creates a new deck and optionally a new note type with custom fields and templates.

Parameters:

deck_name (str): Name for the new Anki deck
model_name (str): Name for the note type/model
fields (list): List of field names (e.g., ['Front', 'Back', 'Extra'])
card_templates (list, optional): Optional list of card template definitions

Returns: JSON object with creation status and details

`list_note_types`

Lists all available note types (models) with comprehensive information.

Parameters: None

Returns: Information about all note types including fields, templates, and styling

`generate_audio`

Generates high-quality audio files from text using Google Cloud Text-to-Speech API with Chirp voices.

Parameters:

text (str): Text to convert to speech
language (str, optional): Language code (default: "cmn-cn" for Chinese)
voice (str, optional): Voice name (default: "cmn-CN-Chirp3-HD-Achernar" for Chinese HD voice)

Returns: JSON object with base64-encoded MP3 audio data and metadata

Setup: Requires GOOGLE_CLOUD_API_KEY environment variable

Features: HD quality voices with natural pronunciation, especially excellent for Chinese language learning

`save_media_file`

Saves base64 encoded media data as a file in Anki's media collection for use in cards.

Parameters:

filename (str): Name of the file to save (e.g., 'audio.mp3', 'image.jpg')
base64_data (str): Base64 encoded file data
media_type (str, optional): Type of media file (default: "audio")

Returns: JSON object with saved filename and success status

Use Case: Save generated audio or other media files for use in Anki cards

`generate_and_save_audio`

Generates audio from text and saves it directly to Anki's media collection in one operation.

Parameters:

text (str): Text to convert to speech and save
filename (str): Name for the audio file (e.g., 'pronunciation.mp3')
language (str, optional): Language code (default: "cmn-cn" for Chinese)
voice (str, optional): Voice name (default: "cmn-CN-Chirp3-HD-Achernar")

Returns: JSON object with filename and sound tag for use in card fields

Setup: Requires GOOGLE_CLOUD_API_KEY environment variable

Use Case: One-step audio generation and saving, returns [sound:filename.mp3] tag ready for card fields

`create_notes_bulk`

Parameters:

deck_name (str): Name of the Anki deck to add notes to
notes_list (list): List of note dictionaries, each containing 'model_name', 'fields', and optionally 'tags'
auto_audio (AutoAudioConfig or null, optional): IMPORTANT: Pass as a dictionary/object with the structure shown below, NOT as a JSON string. Configuration for automatic audio generation:
- enabled (bool, required): Must be true to enable audio generation
- source_field (str, required): Name of field to read text from (e.g., "Front", "Hanzi")
- target_field (str, required): Name of field to write audio tag to (e.g., "Audio")
- language (str, optional): Language code - defaults to "cmn-cn" for Chinese
- voice (str, optional): Voice name - defaults to "cmn-CN-Chirp3-HD-Achernar"
Correct format (dictionary object):
```
{
  "enabled": true,
  "source_field": "Hanzi",
  "target_field": "Audio",
  "language": "cmn-cn",
  "voice": "cmn-CN-Chirp3-HD-Achernar"
}
```
WRONG - Do NOT pass as a string:
```
"{\"enabled\": true, \"source_field\": \"Hanzi\", ...}"  ❌ INCORRECT
```
To disable audio generation, pass null or omit this parameter entirely.

Returns: JSON object with success/failed counts, successful notes array, failed notes array, and audio generation results if enabled

Features:

Uses canAddNotesWithErrorDetail to pre-check which notes can be added
Only attempts to add valid notes, ensuring no batch failures
Provides detailed error reporting for each failed note (duplicates, validation errors, etc.)
Returns note IDs for successfully created notes for further processing
Auto-generates audio files for all notes in a single operation - no need to create notes and then update them separately!
Audio generation reports success/failure for each note individually
Skips audio generation if target field already has content

Use Case: Create 20 Chinese vocabulary cards with audio in one efficient operation instead of creating cards and then updating each one individually

`update_notes_bulk`

Updates multiple notes in a single batch operation for maximum efficiency.

Parameters:

updates (list): List of update dictionaries, each containing 'note_id', 'fields' dict, and optionally 'tags' list

Returns: JSON object with success/failure counts and detailed update results

Use Case: Perfect for batch updates like adding audio files to multiple cards at once

`find_similar_notes`

Finds notes that contain the search text as a substring in any field. Simple and reliable text matching.

Parameters:

deck_name (str): Name of the Anki deck to search in
search_text (str): Text to search for as a substring in any field
case_sensitive (bool, optional): Whether the search should be case sensitive (default: false)
max_results (int, optional): Maximum number of matching notes to return (default: 20)

Returns: JSON object with matching notes and details about which fields contained the search text

Features:

Fast substring matching across all note fields
Case-sensitive or case-insensitive search options
Shows exactly which fields matched the search criteria
No external API dependencies required

Technical Details

Framework: FastMCP (built on FastAPI)
Server Name: "anki-mcp"
AnkiConnect URL: http://localhost:8765
Dependencies: fastapi, fastmcp, requests, uvicorn
External APIs:
- Google Cloud Text-to-Speech API (for audio generation)
Audio Format: MP3 with base64 encoding

Features

HD Audio Generation: Premium quality TTS using Google Cloud Chirp voices, optimized for Chinese pronunciation
Automatic Bulk Audio Generation: Create notes with audio in one operation - no need to create notes and then add audio separately!
Note Updates: Update existing notes with new content like audio files while preserving other fields
Media Management: Direct integration with Anki's media collection for seamless file handling
Bulk Operations: Efficient batch note creation and updates for large datasets
Fast Text Search: Simple substring matching for finding notes containing specific text
Comprehensive Error Handling: Robust error handling for all API failures and edge cases
Smart Data Formatting: Content truncation and formatting for optimal readability
Random Sampling: Efficient sampling for large datasets without memory issues
Custom Templates: Full support for custom card templates and CSS styling
Type Safety: Complete parameter validation using Pydantic
Secure API Key Handling: Environment variable-based API key management
Robust Error Handling: Pre-validation of notes with detailed error reporting for duplicates and other issues
Cross-Language Support: Optimized for Chinese language learning but supports multiple languages