How do I use makemkv-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@makemkv-mcp scan the disc in the drive and rip the longest title" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

makemkv-mcp

Python 3.10+ License: MIT MCP

What is this?

makemkv-mcp is a standalone Model Context Protocol (MCP) server that wraps the makemkvcon command-line tool, exposing disc ripping capabilities as tools that any MCP-compatible client (Claude Desktop, Hivemind, etc.) can call. It runs on the machine with MakeMKV installed and an optical drive attached. The MCP client connects to it remotely via Streamable HTTP or locally via stdio.

Features

Scan optical drives and detect loaded discs
Scan disc contents — titles, streams, durations, sizes, codecs
Rip individual titles or all titles as async background jobs
Full disc backup
Persistent job queue with real-time progress tracking (SQLite-backed)
Auto-rip daemon with configurable strategies (longest, all, min_duration)
Discord webhook and generic webhook notifications
Agent callback notifications for rip lifecycle events
Cross-platform support (Linux, macOS, Windows)
Runs over stdio (local) or Streamable HTTP (remote/network)

Quick Start

From source

git clone https://github.com/hivementality/makemkv-mcp.git
cd makemkv-mcp
pip install .
makemkv-mcp

With pip

pip install .

# Run locally (stdio)
makemkv-mcp

# Run on the network (HTTP)
makemkv-mcp --transport streamable_http --port 8099

With Docker

docker-compose up -d

Installation

Prerequisites

Python 3.10+
MakeMKV with makemkvcon in your PATH — download here
An optical drive (Blu-ray, DVD, etc.)

Linux

# Install MakeMKV (Ubuntu/Debian example)
sudo apt install makemkv-bin makemkv-oss

# Install makemkv-mcp
git clone https://github.com/hivementality/makemkv-mcp.git
cd makemkv-mcp
./install.sh

The installer will offer to set up a systemd service for auto-start.

macOS

# Install MakeMKV from https://www.makemkv.com/

git clone https://github.com/hivementality/makemkv-mcp.git
cd makemkv-mcp
./install.sh

The installer will offer to set up a launchd service for auto-start.

Windows

# Install MakeMKV from https://www.makemkv.com/

git clone https://github.com/hivementality/makemkv-mcp.git
cd makemkv-mcp
.\install.ps1

The installer will offer to create a scheduled task for auto-start at login.

Configuration

Generate the default config file:

makemkv-mcp --init-config

This writes to the platform-specific default location:

Platform	Config path
Linux	`~/.config/makemkv-mcp/config.yaml`
macOS	`~/Library/Application Support/makemkv-mcp/config.yaml`
Windows	`%APPDATA%\makemkv-mcp\config.yaml`

You can also pass --config /path/to/config.yaml or set the MAKEMKV_MCP_CONFIG environment variable.

Full config reference

server:
  host: "0.0.0.0"                # Bind address for HTTP transport
  port: 8099                     # Port for HTTP transport
  transport: "stdio"             # "stdio" or "streamable_http"

makemkv:
  binary: "makemkvcon"           # Path or name of makemkvcon binary
  default_output: "~/makemkv-output"  # Default rip output directory
  min_title_length: 120          # Minimum title duration (seconds) for auto-rip filtering
  timeout: 7200                  # Max seconds for a single rip operation

auto_rip:
  enabled: false                 # Enable auto-rip on disc insertion
  poll_interval: 30              # Seconds between drive polls
  strategy: "longest"            # Title selection: "longest", "all", or "min_duration"
  eject_after: true              # Eject disc after successful rip

notifications:
  agent_notify: true             # Send notifications back to MCP agent
  discord_webhook: null          # Discord webhook URL
  webhook_url: null              # Generic webhook URL (POST JSON)

Usage

With Claude Desktop (stdio)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "makemkv": {
      "command": "makemkv-mcp"
    }
  }
}

With Hivemind / Remote clients (Streamable HTTP)

Start the server on the machine with the optical drive:

makemkv-mcp --transport streamable_http --host 0.0.0.0 --port 8099

Then point your MCP client at it:

{
  "mcpServers": {
    "makemkv": {
      "url": "http://YOUR_IP:8099/mcp"
    }
  }
}

With Docker

# Edit docker-compose.yaml to set your output path and drive device
docker-compose up -d

The container exposes port 8099 by default and expects the optical drive passed through as a device.

MCP Tools Reference

Tool	Type	Description
`makemkv_list_drives`	read-only	List optical drives and disc status
`makemkv_scan_disc`	read-only	Scan disc for titles, streams, durations, sizes
`makemkv_rip_title`	action	Start ripping a single title (returns job ID immediately)
`makemkv_rip_all`	action	Start ripping all titles (returns job ID immediately)
`makemkv_backup_disc`	action	Full disc backup (returns job ID immediately)
`makemkv_job_status`	read-only	Check job progress, status, and result
`makemkv_list_jobs`	read-only	List recent jobs with optional status filter
`makemkv_cancel_job`	destructive	Cancel a queued or running job
`makemkv_eject`	action	Eject disc from drive
`makemkv_monitor`	action	Start, stop, or check status of the auto-rip monitor
`makemkv_get_config`	read-only	Get current configuration as YAML
`makemkv_set_config`	action	Update a config value at runtime (in-memory only)

Tool details

makemkv_list_drives — Lists all detected optical drives with disc status. Returns a markdown table (or JSON). Shows disc name and device path for each drive.

makemkv_scan_disc — Scans a disc and returns all titles with their streams (video, audio, subtitle), durations, sizes, chapter counts, and output filenames. Highlights the longest title.

makemkv_rip_title / makemkv_rip_all / makemkv_backup_disc — All rip operations are async. They create a background job, return the job ID immediately, and the rip runs in the background. Use makemkv_job_status to check progress. The server prevents double-ripping the same drive.

makemkv_set_config — Takes a dot-separated key like auto_rip.enabled and a value. The value is automatically type-coerced to match the existing type. Changes are in-memory only (not persisted to disk), letting agents tweak settings without file writes.

Auto-Rip Mode

Auto-rip monitors your drives and automatically starts ripping when a disc is inserted.

Enable auto-rip

In config.yaml:

auto_rip:
  enabled: true
  poll_interval: 30
  strategy: "longest"
  eject_after: true

Or at runtime via an agent:

Agent: calls makemkv_set_config(key="auto_rip.enabled", value="true")
Agent: calls makemkv_monitor(action="start")

Strategies

Strategy	Behavior
`longest`	Rips only the longest title (usually the main movie)
`all`	Rips every title on the disc
`min_duration`	Rips all titles longer than `makemkv.min_title_length` seconds

How it works

The monitor polls drives every poll_interval seconds
When a new disc is detected (via MD5 fingerprint of drive + disc name), it scans the disc
Based on the strategy, it creates rip job(s)
After a successful rip, the disc is optionally ejected
Notifications are sent through all configured channels

Notifications

Discord webhooks

Create a webhook in your Discord server (Server Settings > Integrations > Webhooks)
Add the URL to your config:

notifications:
  discord_webhook: "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"

Discord notifications include color-coded embeds:

Event	Color	Emoji
Disc detected	Blue	CD
Rip started	Orange	Arrows
Rip completed	Green	Check
Rip failed	Red	X
Disc ejected	Purple	Eject

Embeds include fields for disc name, job ID, status, progress, duration, and errors as applicable.

Generic webhooks

For custom integrations (Home Assistant, Slack via incoming webhook, etc.):

notifications:
  webhook_url: "https://your-service.com/hook"

The server POSTs JSON with this structure:

{
  "event": "rip_completed",
  "data": {
    "id": "a3f7c2d1",
    "job_type": "rip_title",
    "disc_name": "INTERSTELLAR",
    "status": "completed",
    "progress": 100.0,
    "duration_seconds": 2700.5,
    "output_dir": "/output/INTERSTELLAR",
    "result": {
      "success": true,
      "files": ["/output/INTERSTELLAR/title00.mkv"]
    }
  }
}

Agent Notifications

When notifications.agent_notify is true (the default), the server tracks rip lifecycle events internally. MCP agents see updated state the next time they call makemkv_job_status or makemkv_list_jobs — completed jobs will show their final status, output files, and duration.

Events tracked:

disc_detected — a new disc was inserted
rip_started — a rip job began processing
rip_completed — a rip job finished successfully
rip_failed — a rip job encountered an error
disc_ejected — a disc was ejected after ripping

Example Conversations

These show what interacting with an agent connected to makemkv-mcp looks like:

"What drives do I have?"

User: What drives do I have?

Agent: Let me check your optical drives.
> calls makemkv_list_drives()

You have 1 optical drive:
  Drive 0: BD-RE ASUS BW-16D1HT — Disc loaded: INTERSTELLAR (/dev/sr0)

"What's on the disc?"

User: What's on the disc?

Agent: Scanning the disc now...
> calls makemkv_scan_disc(drive_index=0)

Interstellar (INTERSTELLAR):
  Title 0: Interstellar — 2:49:00 — 42.1 GB — 33 chapters  (longest)
  Title 1: Special Features — 0:45:12 — 8.2 GB
  Title 2: Trailer — 0:02:30 — 350 MB

The main movie is Title 0 at 2h49m and 42.1 GB.

"Rip the main movie"

User: Rip the main movie.

Agent: Starting the rip now.
> calls makemkv_rip_title(drive_index=0, title_index=0)

Rip job started! Job ID: a3f7c2d1
Disc: Interstellar | Title: 0 | Output: ~/makemkv-output/Interstellar/

I'll check on it for you.
> calls makemkv_job_status(job_id="a3f7c2d1")

Job a3f7c2d1: running — 34.2%

[Later]
> calls makemkv_job_status(job_id="a3f7c2d1")

Done! Interstellar has been saved to ~/makemkv-output/Interstellar/title00.mkv
(42.1 GB). The disc has been ejected. Total time: 45 minutes.

"Start auto-ripping"

User: Turn on auto-rip so it grabs the main movie whenever I put a disc in.

Agent: I'll enable auto-rip with the "longest" strategy.
> calls makemkv_set_config(key="auto_rip.enabled", value="true")
> calls makemkv_monitor(action="start")

Auto-rip is now active. Whenever you insert a disc, I'll automatically
rip the longest title (usually the main movie) and eject the disc when done.

Development

# Clone and install in development mode
git clone https://github.com/hivementality/makemkv-mcp.git
cd makemkv-mcp
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=makemkv_mcp

# Lint
ruff check .

Project structure

makemkv_mcp/
  server.py          # MCP server, tools, CLI entry point
  makemkv.py         # makemkvcon wrapper, output parser, async runner
  jobs.py            # Persistent job queue (aiosqlite)
  notifications.py   # Discord, webhook, agent notifications
  drive_monitor.py   # Auto-rip polling daemon
  config.py          # Pydantic config models, YAML loader
  platform/          # Platform-specific eject/detect
    linux.py
    darwin.py
    windows.py
tests/
  test_parser.py     # makemkvcon output parsing
  test_jobs.py       # Job queue operations
  test_config.py     # Config loading/saving
  test_notifications.py  # Notification channels
  test_server.py     # Integration tests (mocked makemkvcon)

API / Protocol

This server implements the Model Context Protocol (MCP), an open standard for connecting AI assistants to external tools and data sources. MCP provides a structured way for LLM agents to discover and invoke tools over a transport layer.

makemkv-mcp supports two transports:

stdio — the server communicates over stdin/stdout. Best for local usage where the MCP client runs on the same machine (e.g., Claude Desktop).
Streamable HTTP — the server listens on a port and clients connect via HTTP. Best for network/remote usage where the optical drive is on a different machine than the MCP client.

All tool inputs and outputs follow the MCP tool specification with Pydantic-validated schemas.

License

MIT — see LICENSE file.

makemkv-mcp

What is this?

Features

Quick Start

From source

With pip

With Docker

Installation

Prerequisites

Linux

macOS

Windows

Configuration

Full config reference

Usage

With Claude Desktop (stdio)

With Hivemind / Remote clients (Streamable HTTP)

With Docker

MCP Tools Reference

Tool details

Auto-Rip Mode

Enable auto-rip

Strategies

How it works

Notifications

Discord webhooks

Generic webhooks

Agent Notifications

Example Conversations

"What drives do I have?"

"What's on the disc?"

"Rip the main movie"

"Start auto-ripping"

Development

Project structure

API / Protocol

License

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API