Anki MCP Server

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

1. Install dependencies using uv:

   uv sync
   

2. 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

3. (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'
   

4. 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

1. Ensure dependencies are installed: Make sure you've run uv sync in your anki-mcp directory
2. Find your config file at the location above (create it if it doesn't exist)
3. Update the path: Replace /path/to/your/anki-mcp/ with the actual path to your anki-mcp directory
4. Add your API key:
   • Replace your-google-cloud-api-key-here with your actual Google Cloud API key (for audio generation)
5. 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)