mcp-lrclib

mcp-lrclib

LRCLIB 是一个免费、开放的歌词数据库，由使用者共同构建，并向所有人开放，无需密钥或账户。它收录两种歌词形式：歌曲的纯文本，以及 LRC 格式；后者的每一行都标注了唱到该句的时间，卡拉 OK 显示或歌词面板会据此同步显示。每首歌曲都按标题、艺人、专辑和时长归档，因此同一首歌的不同发行版本会并列显示。

此服务可将聊天客户端连接到该数据库。你可以按标题、艺人或专辑搜索歌曲，查看纯文本歌词，查看带时间戳的同步歌词行，还可以在阅读前查看某个发行版本的元数据。无需 API 密钥或账户。

法语版本

---

安装

一键安装

Claude Code

claude mcp add lrclib -- npx -y mcp-lrclib

Claude Desktop、Cursor 以及使用标准配置格式的任何客户端

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

需要 Node 24 或更高版本，无需设置任何环境变量。

使用 Docker

{
  "mcpServers": {
    "lrclib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lrclib:2.0.1"]
    }
  }
}

-i 会保持 stdin 处于打开状态，协议通过此通道传输；不使用 -t，因为 TTY 会改写数据流。容器只需能够通过 HTTPS 向外连接 lrclib.net，除此之外不需要任何东西：无需卷、端口或凭据。

不使用 npm 的安装包

从最新版本下载 mcp-lrclib-2.0.1.mcpb 并打开。支持 MCP 安装包的客户端会自行完成安装，无需 npm，也无需编辑配置文件。安装包包含其依赖项，因此安装时不会下载任何内容。

你可以询问什么

• “帮我找找 Nino Ferrer 的《Le Sud》歌词。”
• “给我《Bohemian Rhapsody》的同步歌词，这样我可以跟着唱。”
• “LRCLIB 上有哪些版本的《Hallelujah》，每个版本有多长？”
• “把那段歌词的后半部分读给我听。”
• “曲目 3396226 有同步歌词吗？”

通常的使用流程是先搜索，再阅读：search_tracks 会返回一个 id，get_lyrics 则使用该 ID。

工具

工具	功能
search_tracks	按标题、艺人或专辑查找曲目，并返回其元数据。
get_lyrics	读取一首曲目的歌词，可以是纯文本，也可以带时间戳。
get_track	根据曲目 ID 读取一首曲目的元数据，不包含歌词。

LRCLIB 根据曲目的元数据归档，因此可以通过标题、艺人或专辑找到歌曲。记得歌曲里的某句歌词，在这里无法找到结果。

search_tracks

按元数据查找符合条件的曲目，可以进行一次自由文本搜索，也可以按各字段搜索。同一首歌的多个发行版本会并列返回，可通过专辑和时长区分。

参数	类型	必填	功能
query	字符串，1 到 200 个字符	否	自由文本搜索，例如 nino ferrer le sud。
track_name	字符串，最多 200 个字符	否	按字段搜索时使用的歌曲标题。
artist_name	字符串，最多 200 个字符	否	按字段搜索时使用的艺人名称。
album_name	字符串，最多 200 个字符	否	按字段搜索时使用的专辑名称，用于缩小搜索范围。
limit	整数，1 到 50，默认值为 10	否	返回的行数。LRCLIB 每次搜索最多返回 20 条结果。

传入 query，或三个字段之一。

**返回内容：**包含 id 的行，可供 get_lyrics 和 get_track 使用；track_name 和 artist_name；用于区分同一首歌的两个发行版本的 album_name 和 duration_seconds；instrumental；has_plain_lyrics 和 has_synced_lyrics，可用于在请求带时间戳的歌词前确认其是否存在；以及 source_url。此外还会返回 result_count 和 total_available，分别表示应用 limit 前 LRCLIB 返回的曲目数和可用曲目总数。对于未记录专辑名称或时长的曲目，album_name 和 duration_seconds 为 null。这些行不包含歌词：歌词由 get_lyrics 读取。

get_lyrics

读取一首曲目的歌词，可提供纯文本，或带有每行演唱时间的 LRC 行。长歌词会分段提供，并从行边界处继续读取。

参数	类型	必填	说明
id	正整数	否	LRCLIB 曲目 ID，由 search_tracks 返回。
artist_name	最多 200 个字符的字符串	否	艺术家名称，要求完全匹配。未提供 id 时必填。
track_name	最多 200 个字符的字符串	否	歌曲标题，要求完全匹配。未提供 id 时必填。
album_name	最多 200 个字符的字符串	否	专辑名称，用于在不同发行版本中进行选择。
duration_seconds	正数	否	曲目时长，用于在时长不同的版本中进行选择。
format	plain、synced 或 both，默认值为 plain	否	要提供的歌词形式。
max_chars	200 到 20000 之间的整数，默认值为 6000	否	本次调用提供的文本字符数。
offset	大于或等于 0 的整数，默认值为 0	否	用于继续读取的字符偏移量。

返回内容： status，其值为 ok、表示曲目没有歌词的 instrumental，或表示曲目未收录歌词的 no_lyrics；track，包含曲目的 ID、标题、艺术家、专辑、时长和 source_url；plain_lyrics；作为原始 LRC 文本的 synced_lyrics，以及由 { time_seconds, text } 组成的列表 synced_lines，若本次读取截断了这些行，则还会返回 synced_lines_truncated。读取情况由 paginated_form、total_chars、returned_chars、offset、next_offset 和 truncated 描述；传入 next_offset 即可继续读取，其中的 null 表示已到末尾。展示歌词时应引用 attribution 中的内容。status 为 instrumental 时，表示已得到完整答复。

get_track

根据曲目 ID 读取一首曲目的元数据，不包含歌词。可在请求歌词前确认发行版本，也可解析对话中先前提到的 ID。

参数	类型	必填	说明
id	正整数	是	LRCLIB 曲目 ID，由 search_tracks 返回。

返回内容： track，包含搜索结果行中的字段；以及格式为 m:ss 的 duration_formatted，若该曲目未收录时长，则为 null。has_plain_lyrics 和 has_synced_lyrics 表示 get_lyrics 可为该曲目提供哪些形式的歌词。

配置

所有变量均为可选项。请在客户端配置的 env 块中设置。

变量	默认值	作用
LRCLIB_USER_AGENT	项目标识	向 LRCLIB 标识你的应用，并提供可联系到相关人员的地址。
LRCLIB_MIN_INTERVAL_MS	500	两次请求之间的间隔，范围为 200 到 60000。低于下限的值将被拒绝，并使用下限值。
LRCLIB_TIMEOUT_MS	15000	单次请求的截止时间，范围为 1000 到 120000。
LRCLIB_MAX_RETRIES	3	发生临时故障后的重试次数，范围为 0 到 10。
LRCLIB_CACHE_TTL_MS	900000	答案在内存中的保留时间，范围为 0 到 86400000。
LRCLIB_CACHE_MAX_ENTRIES	200	同时保存在内存中的答案数量，范围为 0 到 10000。
LRCLIB_LOG_LEVEL	error	silent、error、info 或 debug，写入 stderr。

超出范围的值将回退为默认值，原因会写入 stderr。

错误

每种故障都带有六种代码之一、错误消息，以及在有帮助时指出下一步操作的提示。

代码	发生了什么	如何处理
not_found	LRCLIB 已响应，但没有这首曲目。	使用 search_tracks 检查拼写。
invalid_input	请求发出前，参数就被拒绝了。	阅读错误消息，其中会指出相应参数。
rate_limited	LRCLIB 要求此客户端降低请求频率。	等待提示中指出的秒数，然后使用相同参数再次调用。曲目仍然存在。
upstream_error	LRCLIB 返回的格式超出此客户端的读取能力。	在问题跟踪器中报告。
network_error	请求未能完成。	稍后重试。
timeout	请求超过了截止时间。	增大 LRCLIB_TIMEOUT_MS，或请求较小的 max_chars。

作为库使用

读取 LRCLIB 的这一层单独发布，包含自己的请求间隔控制、缓存和错误处理，且不绑定任何协议。

import { LrclibClient } from "mcp-lrclib/client";

const client = new LrclibClient();
const { data, cached } = await client.getById(3396226);
console.log(data.track_name, data.synced_lyrics !== null, cached);

search、get 和 getById 各自返回 { data, cached }，并会抛出带有六种代码之一的错误。这里同样会限制两次请求之间的最短间隔。

请求节奏与归属

请求逐一发送，彼此之间至少间隔一段时间，无论服务如何配置，这个间隔下限都不变。User-Agent 始终以项目标识和一个可联系到项目人员的地址结尾。LRCLIB 是一项免费服务，提供供机器读取的 API；本服务会按需读取，每次只发起一个调用，以响应你的请求。

每个结果都包含艺术家、标题和对应的 LRCLIB 页面地址；get_lyrics 还会附带 attribution，三者写在同一行。

歌曲歌词是其作者和出版商的作品。本项目不主张拥有歌词的任何权利，不随附歌词数据库，不向磁盘写入任何内容，也不会向 LRCLIB 回传任何内容。本 MCP 服务是一个非官方项目，与 LRCLIB 无关联。

隐私

本服务不会收集你的任何信息，也不会向其作者发送任何信息。它在你的计算机上运行，只连接 lrclib.net，运行期间将响应保存在内存中，不会向磁盘写入任何内容。 PRIVACY.md 说明了请求会携带哪些内容，以及哪些设置会对此产生影响。

开发

npm install
npm run build:fixtures
npm test
npm run check

测试使用生成的测试样例运行，不会发起网络请求。实时测试套件 npm run test:live 会针对每个路由发起一次请求，并每晚直接对该服务运行。

贡献

请在问题跟踪器中提交错误报告、问题和想法。欢迎提交拉取请求；先创建问题有助于就更改方案达成一致。请参阅CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。歌词属于其作者和出版商，数据库属于 LRCLIB 及其贡献者。

---

mcp-lrclib（法语）

英文版本

LRCLIB 是一个自由、开放的歌曲歌词数据库，由使用者共同维护，免费向所有人开放，无需密钥或账户。它包含歌词的两种形式：歌曲的纯文本歌词，以及 LRC 格式；后者的每一行都标有演唱时间，可用于卡拉 OK 显示或歌词面板。条目按歌曲名称、艺术家、专辑和时长分类，因此同一首歌的不同发行版本会并列显示。

本服务将对话客户端连接到这个数据库。你可以按歌曲名称、艺术家或专辑搜索歌曲，读取纯文本歌词，读取带有时间戳的歌词行，并在读取前核对某个发行版本的条目。无需 API 密钥，无需账户。

安装

一键安装

Claude Code

claude mcp add lrclib -- npx -y mcp-lrclib

Claude Desktop、Cursor 及任何采用标准配置格式的客户端

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

需要 Node 24 或更高版本，无需设置任何环境变量。

使用 Docker

{
  "mcpServers": {
    "lrclib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lrclib:2.0.1"]
    }
  }
}

-i 会保持标准输入处于打开状态，它是协议通道；省略 -t，因为 TTY 会重写数据流。容器只需通过 HTTPS 访问 lrclib.net，无需访问其他地址：不需要卷、端口或凭据。

无需 npm 打包

从最新发布版本 下载 mcp-lrclib-2.0.1.mcpb 并打开。支持 MCP Bundle 的客户端会自行安装，无需 npm，也 无需修改配置文件。Bundle 包含其依赖项，因此安装时不会下载任何内容。

可以提出的请求

• “帮我找找 Nino Ferrer 的《Le Sud》歌词。”
• “给我《Bohemian Rhapsody》的带时间戳歌词，方便我跟唱。”
• “LRCLIB 上有几个版本的《Hallelujah》，时长分别是多少？”
• “读给我听这些歌词的后半部分。”
• “编号为 3396226 的歌曲有同步歌词吗？”

通常的流程是先搜索，再读取：search_tracks 会提供一个 id，get_lyrics 会接收这个标识符。

工具

工具	功能
search_tracks	按歌曲名、艺人或专辑查找曲目，并返回其条目信息。
get_lyrics	读取曲目的歌词，可以是普通歌词或带时间戳的歌词。
get_track	按曲目标识符读取条目信息，不包含歌词。

LRCLIB 根据曲目的条目信息对其分类，因此搜索可以按歌曲名、艺人或专辑查找歌曲。输入歌曲中的一个词无法找到结果。

search_tracks

查找条目信息匹配的曲目，可以使用自由文本搜索或按字段搜索。同一首歌的多个发行版本会并列返回，可通过专辑和时长区分。

参数	类型	必填	功能
query	字符串，1 至 200 个字符	否	自由文本搜索，例如 nino ferrer le sud。
track_name	字符串，最多 200 个字符	否	按字段搜索时使用的歌曲名。
artist_name	字符串，最多 200 个字符	否	按字段搜索时使用的艺人名。
album_name	字符串，最多 200 个字符	否	按字段搜索时使用的专辑名，用于缩小搜索范围。
limit	整数，1 至 50，默认值为 10	否	返回的条目数。每次搜索 LRCLIB 最多返回 20 条。

请传入 query，或三个字段中的任意一个。

**返回内容：**包含 id 的条目，供 get_lyrics 和 get_track 使用；track_name 和 artist_name；用于区分同一首歌不同发行版本的 album_name 和 duration_seconds；instrumental；用于在请求带时间戳的歌词前确认其是否存在的 has_plain_lyrics 和 has_synced_lyrics；以及 source_url。此外还会返回 result_count 和 total_available，分别表示 LRCLIB 返回的条目数，以及应用 limit 前可用的曲目数。若曲目在分类时没有 album_name 或 duration_seconds，这些字段的值为 null。条目不包含歌词，需通过 get_lyrics 读取。

get_lyrics

读取歌曲歌词，支持纯文本或带有每句演唱时间的 LRC 格式。较长的歌词会分段返回，并在行尾处截断。

Argument	Type	Requis	Ce qu'il fait
id	entier, positif	non	search_tracks 返回的 LRCLIB 标识符。
artist_name	chaîne, jusqu'à 200 caractères	non	艺术家名称，精确匹配。不提供 id 时必填。
track_name	chaîne, jusqu'à 200 caractères	non	歌曲名称，精确匹配。不提供 id 时必填。
album_name	chaîne, jusqu'à 200 caractères	non	专辑名称，用于从多个发行版本中选择。
duration_seconds	nombre, positif	non	歌曲时长，用于从时长不同的版本中选择。
format	plain、synced 或 both，默认值为 plain	non	要返回的歌词格式。
max_chars	entier, 200 à 20000, défaut 6000	non	此次调用返回的文本字符数。
offset	entier, 0 ou plus, défaut 0	non	继续读取的字符位置。

返回内容： status，值为 ok、instrumental（歌曲没有可演唱的歌词）或 no_lyrics（歌曲被标记为没有歌词）；track，包含歌曲的标识符、名称、艺术家、专辑、时长和 source_url；plain_lyrics；原始 LRC 文本格式的 synced_lyrics，以及由 { time_seconds, text } 组成的列表 synced_lines；如果分段截断了歌词，还会返回 synced_lines_truncated。读取状态由 paginated_form、total_chars、returned_chars、offset、next_offset 和 truncated 描述：传入 next_offset 即可继续读取，null 表示已到结尾。展示歌词时应引用 attribution 中的内容。若 status 为 instrumental，则表示已完整返回。

get_track

根据标识符读取歌曲信息，不包含歌词。可在请求歌词前确认发行版本，也可解析先前对话中提供的标识符。

Argument	Type	Requis	Ce qu'il fait
id	entier, positif	oui	search_tracks 返回的 LRCLIB 标识符。

返回内容： track，包含搜索结果行的字段；duration_formatted，格式为 m:ss，若歌曲被标记为没有时长则为 null。has_plain_lyrics 和 has_synced_lyrics 表示 get_lyrics 可以返回哪些歌词格式。

配置

所有变量均为可选项。它们设置在客户端配置的 env 块中。

变量	默认值	作用
LRCLIB_USER_AGENT	项目标识	向 LRCLIB 标识您的应用，并提供可联系到相关人员的地址。
LRCLIB_MIN_INTERVAL_MS	500	两次请求之间的间隔，范围为 200 至 60000。低于下限的值会被拒绝，并改用此默认值。
LRCLIB_TIMEOUT_MS	15000	单次请求的超时时间，范围为 1000 至 120000。
LRCLIB_MAX_RETRIES	3	临时失败后的重试次数，范围为 0 至 10。
LRCLIB_CACHE_TTL_MS	900000	响应在内存中的保留时长，范围为 0 至 86400000。
LRCLIB_CACHE_MAX_ENTRIES	200	同时保留在内存中的响应数量，范围为 0 至 10000。
LRCLIB_LOG_LEVEL	error	可设为 silent、error、info 或 debug，日志写入错误输出。

超出范围的值会回退为默认值，原因会写入错误输出。

错误

每种失败都带有六种代码之一和一条消息，并会在有帮助时指出下一步操作。

代码	发生了什么	该怎么做
not_found	LRCLIB 已响应，但未包含此曲目。	使用 search_tracks 检查拼写。
invalid_input	参数在发出请求前被拒绝。	阅读消息，其中会指出具体参数。
rate_limited	LRCLIB 要求此客户端降低请求频率。	等待指定秒数，然后使用相同参数再次调用。曲目仍然存在。
upstream_error	LRCLIB 返回了此客户端无法读取的格式。	在问题跟踪页面报告。
network_error	请求未能完成。	稍后重试。
timeout	请求超时。	增大 LRCLIB_TIMEOUT_MS，或请求更小的 max_chars。

作为库使用

读取 LRCLIB 的这一层单独发布，包含请求节奏控制、缓存和错误处理，不绑定任何协议。

import { LrclibClient } from "mcp-lrclib/client";

const client = new LrclibClient();
const { data, cached } = await client.getById(3396226);
console.log(data.track_name, data.synced_lyrics !== null, cached);

search、get 和 getById 均返回 { data, cached }，并会抛出带有六种代码之一的错误。两次请求之间的间隔下限在此处同样适用。

请求频率与署名

请求逐个发出，彼此之间至少间隔一段时间，无论如何配置，这个间隔下限都始终生效。User-Agent 始终以项目身份和联系负责人的地址结尾。LRCLIB 是一项免费服务，并公开其 API 供机器读取；此服务会按需读取，一次调用一个，以响应您的请求。

每条结果都包含艺术家、曲名和 LRCLIB 页面地址，get_lyrics 则会通过 attribution 将这三项写在一行中。

歌词是其作者和出版商的作品。本项目不主张对歌词拥有任何权利，不内置任何歌词数据库，不向磁盘写入任何内容，也不会向 LRCLIB 贡献任何内容。此 MCP 是一个非官方项目，与 LRCLIB 无关联。

隐私

此服务不会收集您的任何信息，也不会向其作者发送任何信息。它在您的计算机上运行，只连接 lrclib.net，在运行期间将响应保存在内存中，不向磁盘写入任何内容。PRIVACY.md 说明了请求会携带哪些信息，以及哪些设置会改变这一情况。

开发

npm install
npm run build:fixtures
npm test
npm run check

测试使用生成的 fixtures 运行，不会发出任何请求。实时测试套件 npm run test:live 会为每个路由发出一个请求，并且每晚都会针对服务本身运行。

贡献

问题、疑问和想法都可以提交到问题跟踪页面。欢迎提交修改建议；先开一个 issue 有助于就变更形式达成一致。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。歌词属于其作者和出版商，数据库则属于 LRCLIB 及其贡献者。