mpv-mcp-server

mpv-mcp-server

mpv メディアプレーヤーを操作する MCP サーバーです。音楽ライブラリを閲覧したり、再生を操作したり、YouTube からストリーミングしたり、トラックをダウンロードしたりできます。すべて Claude Code などの MCP クライアント内から利用できます。

前提条件

• mpv — メディアプレーヤー（PATH に設定されている必要があります。または MPV_PATH を設定してください）
• Node.js 22+
• yt-dlp (任意) — YouTube のストリーミングとダウンロードに必要です
• ffmpeg (任意) — 音声の抽出、メタデータの読み取り（ffprobe）、タグ付けに必要です

クイックスタート

Claude Code

プロジェクトの .mcp.json に追加します：

{
  "mcpServers": {
    "mpv": {
      "command": "npx",
      "args": ["-y", "mpv-mcp-server"]
    }
  }
}

またはユーザースコープに追加します（すべてのプロジェクトで利用できます）：

claude mcp add mpv --scope user -- npx -y mpv-mcp-server

Claude Desktop

Claude Desktop の設定に追加します：

{
  "mcpServers": {
    "mpv": {
      "command": "npx",
      "args": ["-y", "mpv-mcp-server"]
    }
  }
}

環境変数での上書き

{
  "mcpServers": {
    "mpv": {
      "command": "npx",
      "args": ["-y", "mpv-mcp-server"],
      "env": {
        "MPV_PATH": "/usr/local/bin/mpv",
        "MPV_MEDIA_DIRS": "/home/user/Music,/home/user/Podcasts",
        "MPV_DOWNLOAD_DIR": "/home/user/Music"
      }
    }
  }
}

設定

すべて環境変数で設定します。すべての項目に適切なデフォルト値があります。

変数	デフォルト	説明
MPV_PATH	mpv	mpv 実行ファイルのパス
MPV_IPC_PATH	\\.\pipe\mpvpipe（Windows）または /tmp/mpv-ipc.sock（Unix）	IPC ソケットのパス
MPV_MEDIA_DIRS	~/Music,~/Videos	スキャンするメディアディレクトリ（カンマ区切り）
MPV_DOWNLOAD_DIR	~/Downloads	ダウンロードしたファイルの保存先

ツール

再生

ツール	説明
mpv_play	パスまたは検索語でファイルを再生
mpv_pause	再生を一時停止
mpv_resume	再生を再開
mpv_stop	再生を停止
mpv_status	現在の再生状態を取得
mpv_seek	指定位置にシーク（"90"、"1:30"、"+10"、"-30"）
mpv_volume	音量を取得または設定（0～150）

ライブラリ

ツール	説明
mpv_browse	利用可能なメディアファイルを一覧表示・検索
mpv_playlist	現在のプレイリストを表示
mpv_add	トラックをプレイリストに追加
mpv_load_playlist	プレイリストファイル（.m3u、.pls、.txt）を読み込み
mpv_next	次のトラックにスキップ
mpv_prev	前のトラックに戻る

YouTube

ツール	説明
mpv_youtube	YouTube を検索し、mpv でストリーミング再生（追加モードに対応）
mpv_download	YouTube からダウンロード（音声または動画）

YouTube ツールを使用するには、yt-dlp が PATH に設定されている必要があります。音声のダウンロードには ffmpeg も必要です。

メタデータ

ツール	説明
mpv_info	現在のトラック、または検索語で指定した任意のファイルのメタデータを取得
mpv_tag	ファイルにメタデータタグ（アーティスト、タイトル、アルバム、ジャンル、日付、コメント）を書き込み

どちらのツールも、「Artist - Title」形式のファイル名からアーティスト名とタイトルを推定します。ffmpeg（ffprobe を含む）が必要です。

仕組み

サーバーは mpv の JSON IPC プロトコルを介して通信します。Windows では名前付きパイプを、macOS/Linux では Unix ドメインソケットを使用します。mpv が起動していない場合、サーバーはアイドルモードで自動的に起動します。mpv プロセスは切り離されるため、MCP サーバーが終了しても再生を続けます。

プラットフォーム対応

Windows で開発およびテストされています。macOS/Linux への対応は実装済みですが、テストされていません。問題の報告や PR を歓迎します！

ライセンス

MIT