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 工具要求 PATH 中有 yt-dlp。下载音频还需要 ffmpeg。

元数据

工具	说明
mpv_info	获取当前曲目或通过搜索词查找的任意文件的元数据
mpv_tag	将元数据标签（艺人、标题、专辑、流派、日期、评论）写入文件

这两个工具都会根据“艺人 - 标题”的文件名格式推断艺人和标题。需要 ffmpeg（包含 ffprobe）。

工作原理

此服务通过 mpv 的 JSON IPC 协议与其通信。在 Windows 上使用命名管道，在 macOS/Linux 上使用 Unix 域套接字。如果 mpv 尚未运行，服务会自动以空闲模式启动它。mpv 进程会与服务分离，因此即使 MCP 服务退出，播放也会继续。

平台支持

本项目在 Windows 上开发并经过测试。macOS/Linux 支持已实现，但尚未测试——欢迎提交问题和 PR！

许可证

MIT