Skip to main content
Glama
deenesjakoruzh
Builderstar

youtube-music-cli-mcp

by Builderstar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

[!IMPORTANT] 这是 involvex/youtube-music-cli 的非官方分支，添加了本地 stdio MCP 服务器。它与上游、YouTube 或 Google 均无关联。此自定义分支从源码构建，并非上游宣传的 npm 包。

MCP 的安装、工具、权限和客户端配置请参阅 mcp/README.md。

🎵 youtube-music-cli

一款功能强大的 YouTube Music 终端用户界面（TUI）音乐播放器

License: MIT

功能特性 • 安装 • 使用方法 • 插件 • 文档

功能特性

  • 🎨 精美的 TUI - 基于 React 和 Ink 构建的丰富终端界面

  • 🔍 搜索 - 查找歌曲、专辑、艺术家和播放列表

  • 📋 队列管理 - 构建和管理你的播放队列

  • ❤️ 收藏 - 按 f 将曲目标记为收藏，按 Shift+F 查看收藏

  • 🔀 随机播放与循环 - 多种播放模式

  • 🎚️ 音量控制 - 精细的音量调节

  • 💡 智能推荐 - 发现相关曲目

  • 🎨 主题 - 深色、浅色、午夜、矩阵主题

  • 🔌 插件系统 - 通过插件扩展功能

  • ⌨️ 键盘驱动 - 高效的 vim 风格导航

  • 🖥️ 沉浸模式 - 带音频可视化器和迪斯科效果的全屏 Windows TUI

  • 💾 下载 - 使用 Shift+D 保存曲目/播放列表/艺术家

  • 🏷️ 元数据标签 - 自动标记标题/艺术家/专辑，可选封面图

  • ⚡️ Shell 补全 - ymc completions <bash|zsh|powershell|fish> 输出可 source 或保存的脚本，使 CLI（也可作为 ymc 使用）能够对子命令和标志进行 Tab 补全

Related MCP server: ytm-mcp

支持上游项目

如果你觉得 youtube-music-cli 有用，请考虑支持上游项目的开发：

你的支持有助于这个项目保持活力并不断改进！

路线图

访问 SUGGESTIONS.md 查看完整的待办事项，并使用 docs/roadmap.md 了解当前的实现重点（交叉淡入淡出 + 无缝播放）以及均衡器/增强功能的后续计划。路线图文档还说明了如何接手工作，以便审阅者和贡献者保持一致。

前置要求

必需：

  • mpv - 用于音频播放的媒体播放器

  • yt-dlp - YouTube 音频提取

安装前置要求

# With Scoop
scoop install mpv yt-dlp

# With Chocolatey
choco install mpv yt-dlp
brew install mpv yt-dlp
# Ubuntu/Debian
sudo apt install mpv
pip install yt-dlp

# Arch Linux
sudo pacman -S mpv yt-dlp

# Fedora
sudo dnf install mpv yt-dlp

安装

Node.js（推荐）

需要已安装 Node.js 18+。

npm install -g @involvex/youtube-music-cli

Bun

bun install -g @involvex/youtube-music-cli

Homebrew

brew tap involvex/youtube-music-cli https://github.com/involvex/youtube-music-cli.git
brew install youtube-music-cli

GitHub Releases

https://github.com/involvex/youtube-music-cli/releases

安装脚本（bash）

curl -fssl https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.sh | bash

安装脚本（PowerShell）

iwr https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.ps1 | iex

从源码安装

git clone https://github.com/involvex/youtube-music-cli.git
cd youtube-music-cli

# With bun (recommended for development)
bun install
bun run build
bun link

# With npm
npm install
npm run build
npm link

使用方法

交互模式

启动 TUI：

youtube-music-cli

CLI 命令

# Play a specific track
youtube-music-cli play <video-id|youtube-url>

# Search for music
youtube-music-cli search "artist or song name"

# Play a playlist
youtube-music-cli playlist <playlist-id>

# Get suggestions based on current track
youtube-music-cli suggestions

# Playback control
youtube-music-cli pause
youtube-music-cli resume
youtube-music-cli skip
youtube-music-cli back

沉浸模式（Windows）

启动全屏可视化播放器，支持真实播放、队列控制和音频可视化。需要 mpv 和 yt-dlp（与正常播放相同）。

# Standard immersive mode
youtube-music-cli --win32

# Search and play immediately
youtube-music-cli --win32 --search "artist song"

# With disco mode enabled
DISCO_MODE=true youtube-music-cli --win32

# Standalone Windows binary (Bun compile)
bun run build:win32
dist/ymc-win32.exe

沉浸模式快捷键：

按键

操作

/ 或 S

打开搜索覆盖层

Tab

循环切换搜索类型（查询视图）

Ctrl+A

编辑艺术家筛选器

Ctrl+L

编辑专辑筛选器

= / +

音量增加（+5%，播放器视图）

-

音量降低（-5%，播放器视图）

+

增加搜索结果限制（查询视图）

-

减少搜索结果限制（查询视图）

Shift+D

下载选中的搜索结果

Space

播放 / 暂停

F

切换收藏（当前曲目或搜索）

L

音乐库菜单（播放列表、收藏）

P

打开已保存的播放列表选择器

E

播放所有收藏

Shift+S

切换随机播放

R

循环切换（关闭 → 全部 → 单曲）

,

打开设置覆盖层（WT 上也可用 Ctrl+,）

M

从搜索结果创建混音（结果视图）

D

切换迪斯科模式

↑ / ↓

导航列表（覆盖层）

← / →

上一首 / 下一首曲目

Enter

选择 / 播放（覆盖层）

Esc

返回 / 关闭覆盖层

Q

退出沉浸模式

Ctrl+C

强制退出

页脚在第一行显示随机播放/循环/迪斯科状态，在第二行显示优先快捷键。可从音乐库菜单（L）随机播放收藏。右键单击系统托盘图标可访问设置或退出（使用 assets/icon.ico）。

在 Windows 上使用 Bun 运行时，即使终端未聚焦，全局媒体键（Alt+媒体键）也可正常工作。

沉浸播放故障排查

  • 显示曲目信息但时间不前进 / 没有音频： 按 Space 恢复播放。沉浸模式会自动启动上次的会话；如果 mpv 被外部暂停（屏幕共享、焦点丢失），UI 现在会同步到 PAUSED 状态 — 再次按 Space。

  • 屏幕共享（Discord、Teams、OBS）： 远程观看者通常听不到你电脑的音频，除非你启用"共享电脑声音"/系统音频捕获。这是 Windows 捕获的限制，并非播放器只将音频路由给你。

  • 需要 Bun 才能使用 Win32 原生功能： 全局热键和原生控制台标题通过 Bun 使用 @bun-win32/*。使用 bun run dev:win32 或编译后的 ymc-win32.exe 二进制文件运行。

Shell 补全

通过随 CLI 附带的轻量级 ymc 别名生成 shell 补全辅助脚本。运行 ymc completions <bash|zsh|powershell|fish> 为你的 shell 打印补全脚本，然后 source 它或将其持久化到你的配置文件中：

# Bash
source <(ymc completions bash)
ymc completions bash >> ~/.bash_completion

# Zsh
source <(ymc completions zsh)

# PowerShell
ymc completions powershell | Out-File -Encoding utf8 $PROFILE
Invoke-Expression (ymc completions powershell)

# Fish
ymc completions fish > ~/.config/fish/completions/ymc.fish

如果你使用别名或脚本名称全局安装了 CLI，请确保在生成补全之前 ymc 指向同一个二进制文件，以便脚本与你的安装路径匹配。

选项

标志

短标志

描述

--theme

-t

主题：dark、light、midnight、matrix

--volume

-v

初始音量（0-100）

--shuffle

-s

启用随机播放模式

--repeat

-r

循环模式：off、all、one

--headless

无 TUI 运行

--win32

沉浸式全屏模式（仅限 Windows）

--help

-h

显示帮助

示例

# Launch with matrix theme at 80% volume
youtube-music-cli --theme=matrix --volume=80

# Search and play in headless mode
youtube-music-cli search "lofi beats" --headless

# Play with shuffle enabled
youtube-music-cli play dQw4w9WgXcQ --shuffle

键盘快捷键

全局

按键

操作

?

显示帮助

/

搜索

p

插件管理器

Shift+F

收藏视图

g

推荐

,

设置

Esc

返回

q

退出

播放

按键

操作

Space

播放 / 暂停

n / →

下一首曲目

b / ←

上一首曲目

Shift+→

快进 10 秒

Shift+←

快退 10 秒

=

音量增加

-

音量降低

f

切换收藏

s

切换随机播放

r

循环切换循环模式

导航

按键

操作

↑ / k

上移

↓ / j

下移

Enter

选择

Esc

返回

下载

按键

操作

Shift+D

下载选中的歌曲/艺术家/播放列表或播放列表视图

插件

使用插件扩展 youtube-music-cli！

管理插件

TUI 模式： 按 p 打开插件管理器。

CLI 模式：

# List installed plugins
youtube-music-cli plugins list

# Install from default repository
youtube-music-cli plugins install adblock

# Install from GitHub URL
youtube-music-cli plugins install https://github.com/user/my-plugin

# Enable/disable
youtube-music-cli plugins enable my-plugin
youtube-music-cli plugins disable my-plugin

# Update
youtube-music-cli plugins update my-plugin

# Remove
youtube-music-cli plugins remove my-plugin

可用插件

插件

描述

adblock

屏蔽广告和赞助内容

lyrics

显示同步歌词

scrobbler

提交到 Last.fm

discord-rpc

Discord Rich Presence 集成

notifications

曲目切换时的桌面通知

开发插件

参见 插件开发指南 和 插件 API 参考。

# Start from a template
cp -r templates/plugin-basic my-plugin
cd my-plugin

# Edit plugin.json and index.ts
# Install for testing
youtube-music-cli plugins install /path/to/my-plugin

配置

配置存储在 ~/.youtube-music-cli/config.json：

{
	"theme": "dark",
	"volume": 70,
	"shuffle": false,
	"repeat": "off",
	"streamQuality": "high",
	"downloadsEnabled": false,
	"downloadDirectory": "D:/Music/youtube-music-cli",
	"downloadFormat": "mp3"
}

流质量

质量

描述

low

64kbps - 节省带宽

medium

128kbps - 均衡

high

256kbps+ - 最佳质量

下载设置

  • 在设置（,）中启用/禁用下载。

  • 在设置 → 下载文件夹中设置下载目录。

  • 在设置 → 下载格式中选择格式（mp3 或 m4a）。

  • 下载文件保存为：

    • <downloadDirectory>/<artist>/<album>/<title>.mp3（或 .m4a）

  • MP3/M4A 文件会标记元数据（title、artist、album），并在可用时包含封面图。

故障排查

找不到 mpv

确保 mpv 已安装并在 PATH 中：

mpv --version

启动时，CLI 现在会检查 mpv 和 yt-dlp。在交互式终端中，它可以提示自动运行安装命令（需先明确确认）。

没有音频

  1. 检查音量是否被静音（按 = 增加）

  2. 验证 yt-dlp 是否正常工作：yt-dlp --version

  3. 尝试播放其他曲目

TUI 渲染问题

如果渲染异常，请尝试调整终端窗口大小或重启应用。

插件未加载

  1. 检查 plugin.json 语法是否有效

  2. 验证插件是否已启用：youtube-music-cli plugins list

  3. 检查日志中的错误

贡献

欢迎贡献！

  1. Fork 仓库

  2. 创建功能分支：git checkout -b feature/my-feature

  3. 进行你的修改

  4. 运行测试：bun run test

  5. 提交：git commit -m 'feat: add my feature'

  6. 推送：git push origin feature/my-feature

  7. 打开 Pull Request

开发

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build
bun run build

# Lint and format
bun run lint:fix
bun run format

# Type check
bun run typecheck

技术栈

  • 运行时： Node.js 18+ / Bun

  • UI 框架： Ink（用于 CLI 的 React）

  • 语言： TypeScript

  • 音频： mpv + yt-dlp

  • API： YouTube Music Innertube API

许可证

MIT © Involvex

文档 • 报告 Bug • 请求功能

为音乐爱好者用心打造 ❤️

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • ytm-mcp

    4shil
    F
    license
    Not graded
    quality
    D
    maintenance
    A full-featured YouTube Music MCP server that lets AI assistants control playback, browse history, download songs, and manage playlists via natural language.
    1
    -

  • yt-music-mcp

    peraltafederico
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for YouTube Music that enables searching songs and artists, managing playlists, and authenticating via Google OAuth, using STDIO transport.
    -