Skip to main content
Glama
qq-music-mcp

qq-music-mcp

by wangkezun

QQ Music MCP Server

一个基于 MCP (Model Context Protocol) 的 QQ 音乐 API 服务器,让大语言模型能够搜索音乐、获取歌曲信息、歌词和播放链接。

安装

# 使用 pip
pip install qq-music-mcp

# 或使用 uv
uv pip install qq-music-mcp

Related MCP server: mcp_music_server

在 Claude Desktop 中使用

编辑 Claude Desktop 配置文件:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %AppData%\Claude\claude_desktop_config.json

添加以下配置:

{
  "mcpServers": {
    "qq-music": {
      "command": "uvx",
      "args": ["qq-music-mcp"]
    }
  }
}

或者如果使用 pip 安装:

{
  "mcpServers": {
    "qq-music": {
      "command": "qq-music-mcp"
    }
  }
}

然后重启 Claude Desktop。

功能

提供以下 MCP Tools:

Tool 名称

描述

search_music

搜索歌曲、专辑、歌单等

get_song_detail

获取歌曲详情

get_song_quality

获取歌曲可用音质

get_lyric

获取歌词

get_song_url

获取单首歌曲播放链接

get_batch_song_urls

批量获取歌曲播放链接

get_album_detail

获取专辑详情

get_album_songs

获取专辑歌曲列表

get_playlist_detail

获取歌单详情

get_album_cover

获取专辑封面 URL

VIP 内容访问

如需获取 VIP 歌曲的高品质播放链接,请设置环境变量:

export QQ_MUSIC_COOKIE="your_qq_music_cookie_here"

或在 Claude Desktop 配置中添加:

{
  "mcpServers": {
    "qq-music": {
      "command": "uvx",
      "args": ["qq-music-mcp"],
      "env": {
        "QQ_MUSIC_COOKIE": "your_cookie_here"
      }
    }
  }
}

获取 Cookie 的步骤:

  1. 打开浏览器访问 https://y.qq.com

  2. 登录你的 QQ 账号

  3. 打开开发者工具 (F12) -> Application -> Cookies

  4. 复制完整的 Cookie 字符串

音质类型说明

音质代码

说明

m4a

AAC 格式

128

128kbps MP3

320

320kbps MP3

flac

FLAC 无损

ape

APE 无损

hires

臻品母带 (24bit/192kHz)

atmos

臻品全景声 (Dolby Atmos)

开发

# 克隆项目
git clone https://github.com/yourusername/qq-music-mcp.git
cd qq-music-mcp

# 安装依赖
uv sync

# 运行测试
uv run mcp dev src/qq_music_api/server.py

作为 Python 库使用

import asyncio
from qq_music_api import QQMusicClient

async def main():
    async with QQMusicClient() as client:
        # 搜索歌曲
        result = await client.search("周杰伦")
        print(result)

        # 获取歌词
        lyric = await client.get_lyric("000paPeF1SZp2I")
        print(lyric)

asyncio.run(main())

许可证

MIT

Available Tools

10 tools
get_album_coverA

获取专辑封面图片 URL

Args: album_mid: 专辑的 MID 标识符 size: 图片尺寸,常用值: 150, 300, 500

Returns: 专辑封面图片的 URL

Inputs: album_mid (required), size. Returns: result

get_album_detailB

获取专辑详情

Args: album_mid: 专辑的 MID 标识符

Returns: 专辑详情的 JSON 字符串,包含专辑名、歌手、发行日期、描述、歌曲数量等

Inputs: album_mid (required). Returns: result

get_album_songsA

获取专辑的歌曲列表

Args: album_mid: 专辑的 MID 标识符

Returns: 专辑歌曲列表的 JSON 字符串

Inputs: album_mid (required). Returns: result

get_batch_song_urlsA

批量获取多首歌曲的播放链接

Args: mids: 多个歌曲 MID,用逗号分隔,例如 "mid1,mid2,mid3" quality: 音质类型,可选值: - m4a: AAC 格式 - 128: 128kbps MP3 (默认) - 320: 320kbps MP3 - flac: FLAC 无损 - ape: APE 无损 - hires: 臻品母带 - atmos: 臻品全景声

Returns: 播放链接列表的 JSON 字符串

Inputs: mids (required), quality. Returns: result

get_lyricB

获取歌词

Args: song_mid: 歌曲的 MID 标识符

Returns: 歌词的 JSON 字符串,包含原歌词和翻译歌词(如有)

Inputs: song_mid (required). Returns: result

get_playlist_detailC

获取歌单详情和歌曲列表

Args: playlist_id: 歌单 ID(数字)

Returns: 歌单详情和歌曲列表的 JSON 字符串

Inputs: playlist_id (required). Returns: result

get_song_detailA

获取歌曲详情

Args: song_mid: 歌曲的 MID 标识符

Returns: 歌曲详情的 JSON 字符串,包含歌曲名、歌手、专辑、时长、可用音质等信息

Inputs: song_mid (required). Returns: result

get_song_qualityA

获取歌曲可用的音质列表

Args: song_mid: 歌曲的 MID 标识符

Returns: 可用音质列表的 JSON 字符串。音质类型包括: - m4a: AAC 格式 - 128: 128kbps MP3 - 320: 320kbps MP3 - flac: FLAC 无损 - ape: APE 无损 - hires: 臻品母带 (24bit/192kHz) - atmos: 臻品全景声 (Dolby Atmos)

Inputs: song_mid (required). Returns: result

get_song_urlA

获取单首歌曲的播放链接

Args: song_mid: 歌曲的 MID 标识符 quality: 音质类型,可选值: - m4a: AAC 格式 - 128: 128kbps MP3 (默认) - 320: 320kbps MP3 - flac: FLAC 无损 - ape: APE 无损 - hires: 臻品母带 - atmos: 臻品全景声

Returns: 播放链接的 JSON 字符串。注意:高品质音源可能需要 VIP 权限

Inputs: song_mid (required), quality. Returns: result

search_musicB

搜索 QQ 音乐

Args: keyword: 搜索关键词 search_type: 搜索类型,可选值: song(歌曲), album(专辑), playlist(歌单), mv, lyric(歌词), user(用户) page: 页码,从1开始 page_size: 每页数量,默认20

Returns: 搜索结果的 JSON 字符串

Inputs: keyword (required), page, page_size, search_type. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools map to distinct resources and actions, but get_song_quality duplicates part of get_song_detail (which already includes available qualities), and get_album_cover is a subset of get_album_detail. This creates some ambiguity about which tool to use for quality/cover information.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case: search_music, get_song_detail, get_song_url, get_album_cover, etc. No mixed conventions.

    Tool Count5/5

    10 tools falls comfortably in the ideal range for a music API server. Each tool addresses a specific aspect of music discovery, metadata, and playback without being bloated.

    Completeness4/5

    Core music workflows (search, song detail, quality, URL, lyrics, album info, playlist info) are covered. However, search_music supports MV and user searches but there are no corresponding get_mv_detail or get_user_profile tools, creating dead ends for those search types.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
      C
      quality
      C
      maintenance
      Multi-source music search and playback MCP server supporting QQ Music, NetEase Cloud, and local files with playlist management.
      3
      2
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      A local music retrieval MCP server that lets users search, download, and organize songs via natural language, with lyrics matching from NetEase Cloud Music and LRCLIB, plus local library indexing through SQLite.
      5
      -