### Run MLX Whisper MCP Server with uv

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/README.md

This command starts the MLX Whisper MCP server. It automatically installs dependencies and downloads the Whisper model if it's the first run.

```bash
uv run mlx_whisper_mcp.py
```

--------------------------------

### Install uv and Run Server

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Install the `uv` package manager and use it to run the MLX Whisper MCP server. This is the recommended deployment method.

```bash
curl -sS https://astral.sh/uv/install.sh | bash
uv run mlx_whisper_mcp.py
```

--------------------------------

### Server Startup and Run

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Initializes and starts the FastMCP server, configuring it to run with standard input/output transport.

```python
if __name__ == "__main__":
    log.info("Starting MLX Whisper MCP server...")
    server.run(transport="stdio")
```

--------------------------------

### Run Server with Direct Python Execution

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Execute the server directly using `python3`. Ensure all dependencies are installed beforehand.

```bash
python3 mlx_whisper_mcp.py
```

--------------------------------

### MCP Transcribe Audio Request Example

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

An example of how to call the transcribe_audio tool using the MCP JSON-RPC format. It includes the tool name and its arguments.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "transcribe_audio",
    "arguments": {
      "audio_data": "SUQzBAAAAAAAI1NTVVNJTkZPIgAAA==",
      "file_format": "mp3",
      "language": "en",
      "task": "transcribe"
    }
  }
}
```

--------------------------------

### Install MLX Whisper MCP Server with uv tool run fastmcp

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/README.md

This command installs the MLX Whisper MCP server using `fastmcp`, which handles dependency management via `uv run`. This is the recommended method for integrating with Claude Desktop.

```bash
uv tool run fastmcp install mlx_whisper_mcp.py
```

--------------------------------

### Example transcribe_youtube MCP Request

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

An example of how to call the transcribe_youtube tool using the MCP (Message Queue Protocol) format. This demonstrates the structure for sending tool call requests.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "transcribe_youtube",
    "arguments": {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "language": "en",
      "task": "transcribe",
      "keep_file": true
    }
  }
}
```

--------------------------------

### Example transcribe_youtube MCP Response

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

An example of a successful response from the transcribe_youtube MCP tool. It includes the transcribed text along with the original URL.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "type": "text",
    "text": "Transcription of YouTube video (https://www.youtube.com/watch?v=dQw4w9WgXcQ):\n\nThis is the transcribed content of the YouTube video..."
  }
}
```

--------------------------------

### Example Log Output

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/errors.md

This is an example of the log output format used by the whisper-mcp logger, indicating an error during audio file transcription.

```text
mlx_whisper_mcp.py:95 - Error transcribing audio file: Could not load audio file
```

--------------------------------

### Setup Basic Logging Configuration

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/configuration.md

Configures the root logger with a specific level, format, date format, and RichHandler for enhanced console output. Sets the logger name and level for the application.

```python
logging.basicConfig(
    level="NOTSET",
    format="%(filename)s:%(lineno)d - %(message)s",
    datefmt="[%X]",
    handlers=[RichHandler(console=console)],
)

log = logging.getLogger("whisper-mcp")
log.setLevel(logging.INFO)
```

--------------------------------

### MCP Transcribe Audio Response Example

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

An example of a successful response from the transcribe_audio tool. It contains the transcribed text within the 'result' field.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "type": "text",
    "text": "Transcription:\n\nThe audio content transcribed from base64 data."
  }
}
```

--------------------------------

### Start MLX Whisper MCP Server with stdio Transport

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/configuration.md

This snippet shows the server startup process, including logging the model path, transport type, and download directory. It uses the stdio transport for MCP communication.

```python
if __name__ == "__main__":
    log.info(
        "[bold green]Starting MLX Whisper MCP Server[/bold green]",
        extra={"markup": True},
    )
    log.info(f"[yellow]Using model:[/yellow] {MODEL_PATH}", extra={"markup": True})
    log.info("[bold]Running with stdio transport...[/bold]", extra={"markup": True})
    log.info(f"[blue]Download directory:[/blue] {DATA_DIR}", extra={"markup": True})
    server.run(transport="stdio")
```

--------------------------------

### Download YouTube Video Request

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

Example MCP request to call the download_youtube tool. Specify the YouTube URL and whether to keep the file.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "download_youtube",
    "arguments": {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "keep_file": true
    }
  }
}
```

--------------------------------

### Example Log Output Format

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Shows a typical log message format produced by the configured logger, including filename, line number, and the message content.

```text
mlx_whisper_mcp.py:95 - Error transcribing audio file: Could not load model
```

--------------------------------

### Import mlx_whisper and yt-dlp with Error Handling

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

This snippet demonstrates how to import essential libraries, mlx_whisper and yt-dlp, using try-except blocks. It logs success with rich formatting or warns on import failure, allowing the server to start even if dependencies are missing.

```python
try:
    import mlx_whisper
    log.info("[green]Successfully imported mlx_whisper[/green]", extra={"markup": True})
except ImportError:
    log.warning(
        "Error: MLX Whisper not installed. Install with 'uv pip install mlx-whisper'."
    )

try:
    from yt_dlp import YoutubeDL
    log.info("[green]Successfully imported yt-dlp[/green]", extra={"markup": True})
except ImportError:
    log.warning("Error: yt-dlp not installed. Install with 'uv pip install yt-dlp'.")
```

--------------------------------

### Test Individual Tool with asyncio

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Execute a single tool, such as `transcribe_file`, independently for testing purposes. This example uses asyncio to run the transcription.

```python
import asyncio
from mlx_whisper_mcp import transcribe_file

result = asyncio.run(transcribe_file('/path/to/audio.mp3'))
print(result)
```

--------------------------------

### Example MCP Request for Transcribe File

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

Illustrates the JSON-RPC request format for calling the 'transcribe_file' tool, specifying the file path, language, and task.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "transcribe_file",
    "arguments": {
      "file_path": "/Users/username/Downloads/recording.mp3",
      "language": "en",
      "task": "transcribe"
    }
  }
}

```

--------------------------------

### Example MCP Tool Discovery Output

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

This JSON output represents the metadata for a tool discovered via the MCP protocol. It includes the tool's name, description, and a detailed schema for its input parameters.

```json
{
  "name": "transcribe_file",
  "description": "Transcribe an audio file from disk using MLX Whisper.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "file_path": {
        "type": "string",
        "description": "Path to the audio file"
      },
      "language": {
        "type": "string",
        "description": "Optional language code..."
      },
      "task": {
        "type": "string",
        "enum": ["transcribe", "translate"],
        "description": "Task to perform..."
      }
    },
    "required": ["file_path"]
  }
}
```

--------------------------------

### Download and Transcribe YouTube Videos

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Combines YouTube video downloading and transcription into a single tool. Requires both yt_dlp and mlx_whisper to be installed.

```python
@server.tool
def transcribe_youtube(url: str, model_path: str = MODEL_PATH, output_dir: str = str(DATA_DIR)) -> str:
    """Download and transcribe a YouTube video.

    Args:
        url: The URL of the YouTube video.
        model_path: Identifier for the Whisper model to use.
        output_dir: The directory to save the downloaded video and transcription.

    Returns:
        The transcribed text from the video.
    """
    if not yt_dlp:
        raise RuntimeError("yt_dlp is not installed.")
    if not mlx_whisper:
        raise RuntimeError("mlx_whisper is not installed.")

    video_path = download_youtube(url, output_dir)
    model = mlx_whisper.load(model_path)
    result = model.transcribe(video_path)
    return result["text"]
```

--------------------------------

### Handle MLX Whisper Import Errors

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

This code block demonstrates how to handle potential `ImportError` when importing the `mlx_whisper` library. It logs a success message if the import is successful or a warning if the library is not installed. This ensures the server can start even if MLX Whisper is missing, though tools relying on it will fail at runtime.

```python
try:
    import mlx_whisper
    log.info("[green]Successfully imported mlx_whisper[/green]", extra={"markup": True})
except ImportError:
    log.warning("Error: MLX Whisper not installed...")
```

--------------------------------

### Check MLX Whisper and yt-dlp Import Availability

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Verify if the `mlx_whisper` and `yt_dlp` libraries are installed and importable. This helps in diagnosing import-related issues.

```python
try:
    import mlx_whisper
    print('mlx_whisper: OK')
except ImportError as e:
    print(f'mlx_whisper: FAILED - {e}')

try:
    import yt_dlp
    print('yt_dlp: OK')
except ImportError as e:
    print(f'yt_dlp: FAILED - {e}')
```

--------------------------------

### Download YouTube Videos

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Provides a tool to download YouTube videos using yt-dlp. Requires yt_dlp to be installed.

```python
@server.tool
def download_youtube(url: str, output_dir: str = str(DATA_DIR)) -> str:
    """Download a YouTube video.

    Args:
        url: The URL of the YouTube video.
        output_dir: The directory to save the downloaded video.

    Returns:
        The path to the downloaded video file.
    """
    if not yt_dlp:
        raise RuntimeError("yt_dlp is not installed.")

    Path(output_dir).mkdir(parents=True, exist_ok=True)

    ydl_opts = {
        "outtmpl": str(Path(output_dir) / "%(title)s.%(ext)s"),
        "format": "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best",
        "quiet": True,
        "no_warnings": True,
    }

    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
        info = ydl.extract_info(url, download=True)
        video_title = info.get("title", "video")
        video_ext = ydl.determine_ext("bestvideo")
        return str(Path(output_dir) / f"{video_title}.{video_ext}")
```

--------------------------------

### Logging Setup for MLX Whisper MCP

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Configures logging for the MLX Whisper MCP server using RichHandler for console output and setting the log level to INFO.

```python
logging.basicConfig(
    level=logging.INFO,
    format="%(message)s",
    datefmt="[%X]",
    handlers=[RichHandler(rich_tracebacks=True, markup=True)],
)

log = logging.getLogger("whisper-mcp")
```

--------------------------------

### Navigation Map

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/README.md

This map shows the structure of the documentation, guiding users to different sections.

```markdown
INDEX.md (Start here)
├── api-reference.md (Tool APIs)
├── types.md (Type definitions)
├── mcp-tools.md (MCP protocol)
├── errors.md (Error handling)
├── configuration.md (Settings)
├── architecture.md (System design)
└── implementation-guide.md (Code details)
```

--------------------------------

### Download YouTube Video Response

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

Example MCP response for a successful download_youtube call, returning the file path. A cached file or failed download will return the path or null, respectively.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "type": "text",
    "text": "/Users/username/.mlx-whisper-mcp/downloads/dQw4w9WgXcQ.mp4"
  }
}
```

--------------------------------

### Example MCP Response for Transcribe File

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

Shows the expected JSON-RPC response structure after a successful 'transcribe_file' operation, containing the transcribed text.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "text",
    "text": "Transcription:\n\nHello, this is a test recording of my voice."
  }
}

```

--------------------------------

### PEP 723 Script Metadata for Dependencies

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/configuration.md

This script metadata defines Python version requirements and project dependencies. It allows for automatic dependency installation when running the script with tools like `uv run`.

```python
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "mcp[cli]",
#     "mlx-whisper",
#     "rich",
#     "yt-dlp",
# ]
# ///
```

--------------------------------

### Create Data Directory

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Creates the necessary data directory on server startup. Use `parents=True` to create intermediate directories and `exist_ok=True` to prevent errors if the directory already exists.

```python
DATA_DIR.mkdir(parents=True, exist_ok=True)
```

--------------------------------

### Configure yt-dlp Options

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Sets up configuration options for yt-dlp, specifying the desired format, output template, and suppressing progress/warning messages for cleaner execution.

```python
ydl_opts = {
    "format": "best[ext=mp4]",
    "outtmpl": output_path,
    "quiet": True,
    "no_warnings": True,
    "extract_flat": False,
    "merge_output_format": "mp4",
}
```

--------------------------------

### Initialize FastMCP Server

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/configuration.md

Initializes the FastMCP server with a name and a list of required dependencies. The server uses stdio transport for communication.

```python
server = FastMCP(
    name="mlx-whisper",
    dependencies=["mlx-whisper", "yt-dlp"]
)
```

--------------------------------

### DATA_DIR Configuration

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/api-reference.md

Sets the directory for storing downloaded videos and transcriptions. This directory is created if it doesn't exist.

```python
DATA_DIR = HOME_DIR / ".mlx-whisper-mcp" / "downloads"
```

--------------------------------

### Verify Successful Download

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Confirms that the video file was successfully created after the download attempt and returns the output path upon success.

```python
if Path(output_path).exists():
    log.info(f"Download successful: {output_path}")
    return output_path
```

--------------------------------

### Transcribe YouTube Video

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/api-reference.md

Downloads and transcribes a YouTube video. Use this to get a text transcription of a video from a URL. The downloaded video file is kept by default.

```python
from mlx_whisper_mcp import transcribe_youtube

# Download and transcribe a YouTube video
result = await transcribe_youtube(
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
)
print(result)
# Output:
# Transcription of YouTube video (https://www.youtube.com/watch?v=dQw4w9WgXcQ):
#
# The transcribed text from the YouTube video...
```

```python
# Transcribe and delete the video file afterward
result = await transcribe_youtube(
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    keep_file=False
)
```

```python
# Transcribe with language forcing and translation
result = await transcribe_youtube(
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    language="fr",
    task="translate"
)
```

--------------------------------

### FastMCP Server Initialization

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Initializes the FastMCP server instance for the MLX Whisper MCP application.

```python
server = FastMCP()

@server.dependencies
def get_dependencies():
    return {
        "mlx_whisper": mlx_whisper,
        "yt_dlp": yt_dlp,
    }
```

--------------------------------

### Configure Data Directory

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/configuration.md

Defines the directory for storing downloaded YouTube videos and transcription output. The directory is created automatically if it doesn't exist.

```python
DATA_DIR = HOME_DIR / ".mlx-whisper-mcp" / "downloads"
DATA_DIR.mkdir(parents=True, exist_ok=True)
```

--------------------------------

### Execute YouTube Download

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Uses the yt-dlp library within a context manager to download the YouTube video specified by the URL and configured options.

```python
with YoutubeDL(ydl_opts) as ydl:
    ydl.download([url])
```

--------------------------------

### Define User Home Directory

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/configuration.md

Sets the base directory to the user's home directory using pathlib.Path.home(). This is used as the root for other data directories.

```python
HOME_DIR = Path.home()
```

--------------------------------

### Construct Output Path

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Constructs the output file path using the extracted video ID and a fixed .mp4 extension.

```python
output_path = str(DATA_DIR / f"{video_id}.mp4")
```

--------------------------------

### New Tool Template

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

A template for defining new tools with the `@server.tool()` decorator. Includes error handling, logging, and follows the `verb_noun` naming convention.

```python
@server.tool()
async def new_tool_name(param1: str, param2: bool = True) -> str:
    """Tool description for MCP clients."""
    try:
        # Implementation
        result = perform_operation(param1, param2)
        log.info(f"Operation successful: {result}")
        return f"Success: {result}"
    except Exception as e:
        log.error(f"Error in operation: {str(e)}")
        return f"Error: {str(e)}"
```

--------------------------------

### Handle Download Failure

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Logs an error and returns None if the video file was not found after the download process, indicating a failed download.

```python
else:
    log.error(f"Download failed, file not found: {output_path}")
    return None
```

--------------------------------

### Unsupported Python Import

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Attempting to import functions like 'transcribe_file' directly from the mlx_whisper_mcp module is not supported. The module is not designed for library usage.

```python
from mlx_whisper_mcp import transcribe_file  # Not supported
```

--------------------------------

### Claude Desktop MCP Server Configuration for MLX Whisper

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/README.md

This JSON snippet configures Claude Desktop to use the MLX Whisper MCP server. It specifies the command to run (`uv run mlx_whisper_mcp.py`) and the working directory. Replace the placeholder path with the actual absolute path to your script.

```json
{
  "mcpServers": {
    "mlx-whisper": {
      "command": "uv",
      "args": [
        "run",
        "mlx_whisper_mcp.py"
      ],
      "cwd": "/absolute/path/to/mlx_whisper_mcp/"
    }
  }
}
```

--------------------------------

### Async Tool Decoration Pattern

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

This pattern shows how to define tools as async functions and register them using the @server.tool() decorator. This is required for proper integration with the MCP protocol.

```python
@server.tool()
async def tool_name(param: type) -> str:
    """Tool documentation."""
    # Implementation
```

--------------------------------

### Log with Rich Markup Support

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Illustrates how to use Rich markup within log messages for colored and formatted output. This is useful for highlighting success or error states in logs.

```python
log.info("[green]Successfully imported mlx_whisper[/green]", extra={"markup": True})
```

--------------------------------

### Configure MLX Whisper MCP for Claude Desktop

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Add this configuration to your Claude Desktop settings to integrate the MLX Whisper MCP server. Specify the command, arguments, and working directory.

```json
{
  "mcpServers": {
    "mlx-whisper": {
      "command": "uv",
      "args": ["run", "mlx_whisper_mcp.py"],
      "cwd": "/absolute/path/to/mlx_whisper_mcp/"
    }
  }
}
```

--------------------------------

### Edit Claude Desktop Configuration (Windows)

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/README.md

This command opens the Claude Desktop configuration file on Windows using the 'code' command. This is part of the manual configuration process for integrating the MLX Whisper MCP server.

```bash
# On Windows:
code %APPDATA%\Claude\claude_desktop_config.json
```

--------------------------------

### Check for Existing Downloaded File

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Checks if the video file already exists at the specified output path before initiating a new download. Returns the path immediately if the file is found.

```python
if Path(output_path).exists():
    log.info(f"File already exists: {output_path}")
    return output_path
```

--------------------------------

### Registering a Tool with @server.tool()

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

Use the `@server.tool()` decorator to register functions as tools with the FastMCP server. The docstring of the tool function provides a description that clients can use.

```python
import mcp.server.fastmcp

server = mcp.server.fastmcp.FastMCP()

@server.tool()
async def tool_name(...) -> str:
    """Tool docstring provides tool description to clients."""
    pass
```

--------------------------------

### Transcribe Local Audio File

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Use this tool to transcribe audio from a local file. It handles file validation, transcription using MLX Whisper, and saving the output to a .txt file in the data directory.

```python
@server.tool()
async def transcribe_file(
    file_path: str | Path,
    language: Optional[str] = "en",
    task: Literal["transcribe", "translate"] = "transcribe",
) -> str:
    assert Path(file_path).exists(), f"File not found: {file_path}"
    transcript = mlx_whisper.transcribe(
        file_path, path_or_hf_repo=MODEL_PATH, language=language, task=task
    )["text"]
    output_file = str(Path(file_path).with_suffix(".txt"))
    output_file = Path(DATA_DIR) / Path(output_file).name
    with open(output_file, "w", encoding="utf-8") as f:
        f.write(transcript)
    log.info(f"Saving transcript to: {output_file}")
    return f"Transcription:\n\n{transcript}"
    except Exception as e:
        log.error(f"Error transcribing audio file: {str(e)}")
        return f"Error transcribing audio file: {str(e)}"
```

--------------------------------

### download_youtube

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/README.md

Download a YouTube video.

```APIDOC
## download_youtube(url, keep_file=True) -> str | None

### Description
Download a YouTube video.

### Parameters
#### Query Parameters
- **url** (str) - Required - The URL of the YouTube video.
- **keep_file** (bool) - Optional - Whether to keep the downloaded file (default: True).
```

--------------------------------

### Handle YouTube Download Failure

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/errors.md

This snippet demonstrates how the transcribe_youtube function handles cases where the YouTube download fails, returning an error message if the audio path is None.

```python
result = await transcribe_youtube("https://www.youtube.com/watch?v=invalid")
# Returns: "Error: None" (if download_youtube returns None)
```

--------------------------------

### Configure Rich Logging Handler

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Sets up a basic logging configuration using RichHandler for enhanced terminal output. It configures the console to output to stderr and sets the logger name and level.

```python
console = Console(stderr=True)

logging.basicConfig(
    level="NOTSET",
    format="%(filename)s:%(lineno)d - %(message)s",
    datefmt="[%X]",
    handlers=[RichHandler(console=console)],
)

log = logging.getLogger("whisper-mcp")
log.setLevel(logging.INFO)
```

--------------------------------

### download_youtube

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/api-reference.md

Downloads a YouTube video to disk using yt-dlp. It handles video extraction, file path construction, and utilizes yt-dlp for the download process, returning the path to the downloaded MP4 file or None if the download fails.

```APIDOC
## Tool: download_youtube

### Description
Downloads a YouTube video to disk using yt-dlp. It handles video extraction, file path construction, and utilizes yt-dlp for the download process, returning the path to the downloaded MP4 file or None if the download fails.

### Signature
```python
async def download_youtube(url: str, keep_file: bool = True) -> str
```

### Parameters
#### Parameters
- **url** (str) - Required - YouTube video URL (standard YouTube URL format)
- **keep_file** (bool) - Optional - If True, the downloaded file is retained; if False, it would be deleted (though this parameter is not used within the function itself). Default: True

### Return Type
**str | None** — Path to the downloaded `.mp4` file as a string, or None if download fails

### Behavior
1. Extracts the video ID from the YouTube URL (splits on `v=` and `&`).
2. Constructs output path: `~/.mlx-whisper-mcp/downloads/{video_id}.mp4`.
3. Checks if the file already exists; if so, returns the existing path without downloading.
4. Configures yt-dlp options for best available MP4 format, output template, quiet mode, suppressed warnings, and MP4 merge output format.
5. Downloads the video using `YoutubeDL.download()`.
6. Verifies the file exists and returns the path.
7. On error or if the file is not created, returns None.

### Example Usage
```python
from mlx_whisper_mcp import download_youtube

# Download a YouTube video
path = await download_youtube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(f"Downloaded to: {path}")

# Calling again with same URL returns cached file
path2 = await download_youtube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# Returns same path without re-downloading
```

### Throws
This function does not raise exceptions. Errors are caught and None is returned.
```

--------------------------------

### File Structure of MLX Whisper MCP

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Illustrates the directory layout and key files for the MLX Whisper MCP project.

```text
mlx-whisper-mcp/
├── mlx_whisper_mcp.py       # Main application file
├── pyproject.toml            # Project metadata and dependencies
├── README.md                 # User documentation
├── LICENSE                   # Apache License 2.0
├── .gitignore                # Git ignore rules
├── .python-version           # Python 3.12
└── uv.lock                   # Locked dependency versions
```

--------------------------------

### Fail-Open Error Handling Pattern

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

This pattern demonstrates how to catch exceptions and return error messages as strings. It is used to ensure clients always receive a response without needing to handle exceptions themselves.

```python
try:
    # Perform operation
    result = operation()
    return f"Success: {result}"
except Exception as e:
    log.error(f"Error: {str(e)}")
    return f"Error: {str(e)}"
```

--------------------------------

### transcribe_file

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/README.md

Transcribe an audio file from disk.

```APIDOC
## transcribe_file(file_path, language="en", task="transcribe") -> str

### Description
Transcribe an audio file from disk.

### Parameters
#### Path Parameters
- **file_path** (str) - Required - The path to the audio file.
- **language** (str) - Optional - The language of the audio (default: "en").
- **task** (str) - Optional - The task to perform (e.g., "transcribe", "translate") (default: "transcribe").
```

--------------------------------

### Edit Claude Desktop Configuration (macOS)

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/README.md

This command opens the Claude Desktop configuration file on macOS using the 'code' command. This is part of the manual configuration process for integrating the MLX Whisper MCP server.

```bash
# On macOS:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

--------------------------------

### download_youtube

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/README.md

Downloads a YouTube video. Optionally keeps the downloaded file.

```APIDOC
## download_youtube

### Description
Downloads a YouTube video.

### Parameters
#### Request Body
- **url** (string) - Required - YouTube video URL
- **keep_file** (boolean) - Optional - If True, keeps the downloaded file (default: True)
```

--------------------------------

### Enable Debug Logging in Python

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Modify the logger level to DEBUG to see more detailed messages. Restart the server after making this change.

```python
log.setLevel(logging.DEBUG)  # Changed from logging.INFO
```

--------------------------------

### transcribe_file()

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/INDEX.md

Transcribe audio from a file on disk. This tool is part of the public API and can be invoked directly by users.

```APIDOC
## transcribe_file()

### Description
Transcribes audio content from a specified file path.

### Method
(Not specified, likely an SDK function call or RPC method)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
- **file_path** (str | Path) - Required - The path to the audio file to transcribe.

#### Query Parameters
(Not specified)

#### Request Body
(Not specified)

### Request Example
(Not specified)

### Response
#### Success Response (200)
- **transcription** (str) - The transcribed text from the audio file.

#### Response Example
(Not specified)

### Error Handling
- File not found
- Transcription errors
```

--------------------------------

### download_youtube()

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/INDEX.md

Downloads YouTube videos. This tool is part of the public API and can be invoked directly by users.

```APIDOC
## download_youtube()

### Description
Downloads the audio or video content from a YouTube URL.

### Method
(Not specified, likely an SDK function call or RPC method)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
(Not specified)

#### Query Parameters
(Not specified)

#### Request Body
- **youtube_url** (str) - Required - The URL of the YouTube video to download.

### Request Example
(Not specified)

### Response
#### Success Response (200)
- **download_path** (str) - The local path where the YouTube video was saved.

#### Response Example
(Not specified)

### Error Handling
- Invalid URLs
- Download failures
- File existence checks
```

--------------------------------

### Python Imports for MLX Whisper MCP

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Shows the necessary imports for the MLX Whisper MCP server, including standard libraries, third-party packages, and conditional imports for optional dependencies.

```python
import base64
import logging
import os
import tempfile
from pathlib import Path

from mcp.server.fastmcp import FastMCP
from rich.logging import RichHandler

try:
    import mlx_whisper
except ImportError:
    mlx_whisper = None
    logging.warning("mlx_whisper not found. Transcription features will be unavailable.")

try:
    import yt_dlp
except ImportError:
    yt_dlp = None
    logging.warning("yt_dlp not found. YouTube download features will be unavailable.")
```

--------------------------------

### Transcribe Audio from Base64 Data

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Implements a tool to transcribe audio directly from base64 encoded data using MLX Whisper.

```python
@server.tool
def transcribe_audio(audio_base64: str, model_path: str = MODEL_PATH) -> str:
    """Transcribe audio from base64 data.

    Args:
        audio_base64: Base64 encoded audio data.
        model_path: Identifier for the Whisper model to use.

    Returns:
        The transcribed text.
    """
    if not mlx_whisper:
        raise RuntimeError("mlx_whisper is not installed.")

    audio_bytes = base64.b64decode(audio_base64)
    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp_audio_file:
        tmp_audio_file.write(audio_bytes)
        tmp_audio_path = tmp_audio_file.name

    try:
        model = mlx_whisper.load(model_path)
        result = model.transcribe(tmp_audio_path)
        return result["text"]
    finally:
        os.remove(tmp_audio_path)
```

--------------------------------

### Define transcribe_youtube Tool

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

Defines the transcribe_youtube tool with its asynchronous function signature, parameters, and return type. Use this to integrate YouTube video transcription into your application.

```python
import typing
from typing import Optional

# Assume server is a pre-defined object for tool registration
# class Server:
#     def tool(self):
#         def decorator(func):
#             # Tool registration logic here
#             return func
#         return decorator
# server = Server()

@server.tool()
async def transcribe_youtube(
    url: str,
    language: Optional[str] = "en",
    task: str = "transcribe",
    keep_file: bool = True,
) -> str:
    pass
```

--------------------------------

### transcribe_youtube

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/README.md

Download and transcribe a YouTube video.

```APIDOC
## transcribe_youtube(url, language="en", task="transcribe", keep_file=True) -> str

### Description
Download and transcribe a YouTube video.

### Parameters
#### Query Parameters
- **url** (str) - Required - The URL of the YouTube video.
- **language** (str) - Optional - The language of the audio (default: "en").
- **task** (str) - Optional - The task to perform (e.g., "transcribe", "translate") (default: "transcribe").
- **keep_file** (bool) - Optional - Whether to keep the downloaded file (default: True).
```

--------------------------------

### Clear Video Cache

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Use this command to remove all downloaded videos from the cache directory.

```bash
rm -rf ~/.mlx-whisper-mcp/downloads/
```

--------------------------------

### transcribe_youtube()

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/INDEX.md

Downloads and transcribes YouTube videos. This tool is part of the public API and can be invoked directly by users.

```APIDOC
## transcribe_youtube()

### Description
Downloads a YouTube video and then transcribes its audio content.

### Method
(Not specified, likely an SDK function call or RPC method)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
(Not specified)

#### Query Parameters
(Not specified)

#### Request Body
- **youtube_url** (str) - Required - The URL of the YouTube video to download and transcribe.

### Request Example
(Not specified)

### Response
#### Success Response (200)
- **transcription** (str) - The transcribed text from the YouTube video's audio.

#### Response Example
(Not specified)

### Error Handling
- Download failures
- Missing files
- Transcription errors
```

--------------------------------

### download_youtube

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/mcp-tools.md

Downloads a YouTube video or extracts its audio. It checks for existing files to enable caching and returns the file path upon successful download or if the file is already present. Returns None if the download fails.

```APIDOC
## Tool: download_youtube

### Description

Downloads a YouTube video or extracts its audio. This tool supports caching by checking if the video has already been downloaded.

### Method Signature

```python
async def download_youtube(url: str, keep_file: bool = True) -> str
```

### Parameters

#### Input Schema

- **url** (string) - Required - YouTube video URL (e.g., https://www.youtube.com/watch?v=...)
- **keep_file** (boolean) - Optional - Default: True - Retain the downloaded file. (Note: This parameter is not actively used in this tool's current implementation but is meaningful for related functionalities like `transcribe_youtube`.)

### Response

**Output Type:** string (file path) or null

**Success Response:**

Returns the file path of the downloaded video (e.g., `/Users/username/.mlx-whisper-mcp/downloads/VIDEO_ID.mp4`).

**Error/Cached Response:**

Returns the file path if the file was found or downloaded successfully. Returns `None` if the download fails.

### Example Request (MCP Format)

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "download_youtube",
    "arguments": {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "keep_file": true
    }
  }
}
```

### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "type": "text",
    "text": "/Users/username/.mlx-whisper-mcp/downloads/dQw4w9WgXcQ.mp4"
  }
}
```
```

--------------------------------

### Conditional Cleanup Pattern

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

This pattern manages disk space by conditionally cleaning up temporary and downloaded files. Temporary files are always removed, while downloaded files are kept or deleted based on the 'keep_file' parameter.

```python
# Temporary files (base64 audio)
os.unlink(audio_path)

# Downloaded files (YouTube)
if not keep_file and os.path.exists(audio_path):
    os.unlink(audio_path)
```

--------------------------------

### transcribe_audio()

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/INDEX.md

Transcribe audio data provided as a base64-encoded string. This tool is part of the public API and can be invoked directly by users.

```APIDOC
## transcribe_audio()

### Description
Transcribes audio from base64-encoded data.

### Method
(Not specified, likely an SDK function call or RPC method)

### Endpoint
(Not specified)

### Parameters
#### Path Parameters
(Not specified)

#### Query Parameters
(Not specified)

#### Request Body
- **audio_data** (str) - Required - Base64 encoded audio data.

### Request Example
(Not specified)

### Response
#### Success Response (200)
- **transcription** (str) - The transcribed text from the audio data.

#### Response Example
(Not specified)

### Error Handling
- Base64 decode errors
- Transcription errors
```

--------------------------------

### Configuration Constants for MLX Whisper MCP

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/architecture.md

Defines essential configuration constants used throughout the MLX Whisper MCP server, including model paths and directories.

```python
MODEL_PATH = "community/tiny"
HOME_DIR = Path.home()
DATA_DIR = HOME_DIR / ".cache" / "mlx-whisper-mcp"
```

--------------------------------

### Transcribe Base64 Encoded Audio Data

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

This tool transcribes audio data provided as a Base64 encoded string. It decodes the data, saves it to a temporary file, performs transcription, and cleans up the temporary file.

```python
audio_bytes = base64.b64decode(audio_data)
with tempfile.NamedTemporaryFile(
    suffix=f".{file_format}", delete=False
) as temp_file:
    audio_path = temp_file.name
    audio_bytes = base64.b64decode(audio_data)
    temp_file.write(audio_bytes)
output_file = str(Path(audio_path).with_suffix(".txt"))
output_file = Path(DATA_DIR) / Path(output_file).name
log.info(f"Saving transcript to: {output_file}")
with open(output_file, "w", encoding="utf-8") as f:
    f.write(transcript)
os.unlink(audio_path)
```

--------------------------------

### File Path Type (String or Path)

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/types.md

Represents a filesystem path that can be a string or a pathlib.Path object. The function internally converts the input to a Path object for validation.

```python
str | Path
```

--------------------------------

### Validate Downloaded Audio File

Source: https://github.com/kachio/mlx-whisper-mcp/blob/main/_autodocs/implementation-guide.md

Performs a validation check to ensure the audio file was successfully downloaded and exists before proceeding with transcription. Returns an error message if validation fails.

```python
if audio_path is None or not Path(audio_path).exists():
    log.error(f"Error downloading video: {audio_path}")
    return f"Error: {audio_path}"
```