Skip to main content
Glama
lxmusic

lxmusic

by tiancheng91

Features

  • 多音源 — QQ音乐(tx)、网易云(wy)、本地文件扫描(local)

  • 搜索 — 音乐 / 专辑,音源间自由切换

  • 播放 — 获取播放直链或本地路径,--json 含歌词

  • 下载 — 单曲 / 整张专辑下载,带进度条,自动降级音质

  • 歌单 — YAML 存储,创建、搜索添加(多选)、查看、播放、导出 M3U8

  • 本地源 — 扫描音乐目录,同时解析 YAML 歌单文件,search album 按歌单名匹配

  • 配置 — lxmusic config set 运行时修改,只需关心 data_dir + music_dir

  • MCP — 标准 MCP server(搜索/播放工具)

  • 多音质 — 128k / 320k / FLAC / Hi-Res,不可用时自动降级

Related MCP server: netease-mcp

Quick Start

# 安装
uv tool install lxmusic
# 或: pipx install lxmusic

# 设置 API 密钥(从 https://source.shiqianjiang.cn/ 获取)
lxmusic config set api_key your_key_here

# 搜索音乐(QQ音乐)
lxmusic search music "周杰伦"

# 搜索音乐(网易云)
lxmusic search music "周杰伦" --source wy

# 搜索专辑
lxmusic search album "范特西"

# 播放,返回 URL 和歌词
lxmusic play 102065756 --json

# 下载单曲
lxmusic download 102065756 --dir ~/Music

# 下载整张专辑(先搜索得到 album_id,再下载)
lxmusic album 003DFRzD192KKD --dir ~/Music/七里香

# 启动 MCP server
lxmusic mcp

Installation

从 PyPI

uv tool install lxmusic
# 或: pipx install lxmusic

从源码

git clone <repo-url>
cd lxmusic
uv sync

CLI Usage

lxmusic search music "儿歌" --page 1
lxmusic search album "范特西"
lxmusic search music "周杰伦" --source wy --json
lxmusic search album "我的最爱" --source local      # 本地歌单匹配

Play

lxmusic play 102065756
lxmusic play 102065756 --quality flac
lxmusic play 102065756 --json
{
  "url": "http://...mp3",
  "quality": "320k",
  "lyric": "[ti:七里香]\n...",
  "song": { "id": 102065756, "title": "七里香", "artist": "周杰伦", ... }
}

Download

lxmusic download 102065756                          # 当前目录
lxmusic download 102065756 --dir ~/Music             # 指定目录
lxmusic download 509781655 --source wy --dir ~/Music # 网易云歌曲

Album

lxmusic album 003DFRzD192KKD                          # 远程专辑
lxmusic album "巧虎儿歌" --source local                 # 本地歌单曲目
lxmusic album 003DFRzD192KKD --dir ~/Music/七里香       # 指定目录
lxmusic album 003DFRzD192KKD --quality flac             # 无损音质
lxmusic album 003DFRzD192KKD --json                     # JSON 输出

Playlist

lxmusic playlist create "我的最爱"
lxmusic playlist add "我的最爱" "周杰伦 七里香"          # 搜索 → 交互选择 → 下载 → 添加
lxmusic playlist add "我的最爱" "周杰伦 晴天"             # 回车=全部,逗号分隔多选
lxmusic playlist show "我的最爱"
lxmusic playlist play "我的最爱"
lxmusic playlist export "我的最爱" --dir ~/Music          # 导出 M3U8

Config

lxmusic config set api_key your_key_here                 # 设置密钥
lxmusic config set default_source local                  # 默认本地源
lxmusic config set music_dir ~/Music                     # 音乐文件目录
lxmusic config set data_dir ~/.config/lxmusic             # 数据目录
lxmusic config set default_quality flac                   # 默认音质
lxmusic config set api_key ""                             # 删除配置项
lxmusic config show                                       # 查看当前配置

MCP Server

标准 MCP

lxmusic mcp

标准工具:search_music, search_album, play_music

Local Source

本地源支持两种资产:

  • 音频文件 — .mp3 .flac .wav .m4a .ogg .wma,按文件名搜索

  • 歌单 YAML — 目录下 *.yaml 文件,解析 name + tracks 结构,通过 search album 匹配歌单名

YAML 格式示例(巧虎儿歌.yaml):

name: 巧虎儿歌
tracks:
  - {"id": 1, "title": "小毛驴", "artist": "儿童歌曲", "path": "/music/小毛驴.mp3"}
  - {"id": 2, "title": "粉刷匠", "artist": "儿童歌曲", "path": "/music/粉刷匠.mp3"}

Configuration

配置项说明

优先级:环境变量 > config.yaml > 默认值

Environment Variable

Description

Default

LX_MUSIC_API_KEY

API 密钥(必填)

—

LX_MUSIC_API_URL

后端 API 地址

https://source.shiqianjiang.cn/api/music

LX_MUSIC_DEFAULT_SOURCE

默认音源(tx/wy/local)

tx

LX_MUSIC_DEFAULT_QUALITY

默认音质(128k/320k/flac/hires)

320k

LX_MUSIC_DATA_DIR

lxmusic 数据目录

~/.config/lxmusic

LX_MUSIC_MUSIC_DIR

本地音乐目录(逗号分隔多目录)

~/.config/lxmusic/library

目录结构

用户只需要关心两个路径:数据放哪 和 音乐文件在哪,其余子目录自动推导:

data_dir/                    # lxmusic 数据目录(默认 ~/.config/lxmusic)
├── config.yaml              # 配置文件
├── playlists/               # 歌单 YAML 文件
├── cache/                   # 下载缓存(playlist add 下载的音频)
├── library/                 # 曲库索引
└── history/                 # 播放历史

music_dir/                   # 用户音乐文件目录(可多个,逗号分隔)
└── 巧虎儿歌/
    ├── *.mp3
    └── 巧虎儿歌.yaml        # 歌单文件(自动识别)

配置示例

# ~/.config/lxmusic/config.yaml
api_key: your_key_here
api_url: https://source.shiqianjiang.cn/api/music
default_source: local          # 默认使用本地源
default_quality: 320k
data_dir: ~/.config/lxmusic     # 数据目录
music_dir: ~/Music,/mnt/music  # 本地音乐目录(多个用逗号分隔)

常用命令

# 查看当前配置
lxmusic config show

# 设置 API 密钥
lxmusic config set api_key your_key_here

# 切换默认音源
lxmusic config set default_source local

# 设置本地音乐目录(支持多个)
lxmusic config set music_dir "~/Music,/mnt/music"

# 改变数据目录
lxmusic config set data_dir ~/.config/lxmusic

# 删除配置项(恢复默认)
lxmusic config set api_key ""

路径说明

  • playlist_dir → data_dir/playlists/ — lxmusic playlist 命令操作的文件

  • cache_dir → data_dir/cache/ — lxmusic playlist add 下载的音频缓存

  • local_dirs → music_dir 的值 — LocalSource 扫描的目录

  • lxmusic download 默认下载到当前目录,--dir 指定其他位置

Build & Publish

uv build
uv publish

License

MIT

Available Tools

3 tools
play_musicD

Inputs: source, quality, song_id, songmid.

search_albumD

Inputs: query (required), page, source.

search_musicD

Inputs: query (required), page, source.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.1/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: search_music finds tracks, search_album finds albums, and play_music plays a selected item. Names clearly differentiate the purposes, so an agent can easily select the right tool.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: search_music, search_album, play_music. No mixed conventions, making the API predictable.

    Tool Count4/5

    With 3 tools, the server is minimal but well-scoped for its apparent purpose of music search and playback. It sits at the lower end of the ideal range but each tool earns its place.

    Completeness4/5

    The core workflow is covered: search for music or albums, then play. Minor gaps like pause/stop or playlist management are absent, but these may be outside the intended scope.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for controlling local music playback via NetEase Cloud Music, enabling search, play, pause, skip, and lyrics display through a local web player.
      13
      87
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables AI assistants to search and retrieve music data (songs, lyrics, playlists, albums, artists) from Netease Cloud Music.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server for NetEase Cloud Music data, enabling querying of songs, artists, albums, playlists, lyrics, and user library through tools like search and get details.
      15
      5
      MIT