mcp-lyricscom

mcp-lyricscom

lyrics.com 是一个大型的公开歌词目录。 它按照歌曲标题、艺人、所属专辑和年份收录歌曲，并保存歌词原文。它的搜索功能也能在歌词原文中查找。

此服务可将聊天客户端连接到该目录。你可以根据记得的一句歌词搜索歌曲， 也可以按标题和艺人搜索，并分段阅读某首歌曲的歌词，同时在文本中定位 你要查找的歌词。无需 API 密钥或账户。

Version française

---

安装

一键安装

Claude Code

claude mcp add lyricscom -- npx -y mcp-lyricscom

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

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

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

使用 Docker

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

-i 会保持 stdin 开启，协议通过 stdin 传输；不使用 -t，因为 TTY 会重写数据流。容器只需能通过 HTTPS 访问 www.lyrics.com，除此之外无需任何配置：不需要卷、端口或凭据。

打包安装，无需 npm

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

你可以这样提问

• “哪首歌里有‘I've got a hand for you’这句歌词？”
• “帮我找 Glen Campbell 演唱的 Wichita Lineman 的歌词。”
• “给我读一下这段歌词的后半部分。”
• “这首歌的哪个地方出现了 ‘lineman’ 这个词？”
• “这首歌收录在哪些专辑中？”

常规流程是先搜索，再阅读：搜索结果中的一行会包含一个 id，而 get_lyrics 使用这个 id。

工具

工具	功能说明
search_lyrics	根据歌词中的一句歌词查找歌曲。
search_songs	按标题查找歌曲，并可按艺人缩小范围。
get_lyrics	一次读取一首歌曲的一部分歌词。

search_lyrics

根据歌词中的内容查找歌曲。该网站的排序比较宽松，因此在返回结果前会验证匹配项。

参数	类型	必填	功能说明
query	string，1 到 120 个字符	是	要查找的歌词句子或片段。
limit	integer，1 到 50，默认值为 10	否	返回的行数。
page	integer，1 到 20，默认值为 1	否	返回哪一页结果。
verify	snippet、full 或 none，默认值为 snippet	否	如何确认歌词中确实包含所查内容。
include_excerpt	boolean，默认值为 true	否	在每条结果中附带匹配的歌词。

verify 决定如何评估一条结果。snippet 会检查网站已返回的摘录，不会产生额外开销。full 会获取最多五个歌曲页面并检查完整歌词，这种方式较慢，也可能导致触发速率限制。none 则直接返回网站排序后的结果，不进行检查。

返回内容： 每行都包含 id，可供 get_lyrics 使用；title；artist；album 和 year，如果目录中未注明，则为 null；source_url；以及匹配的歌词 excerpt。raw_result_count 表示网站返回的结果数，filtered_out 表示检查后移除的结果数，两者可以反映排序有多宽松。可通过 has_more 和 next_page 继续获取结果。

search_songs

按标题查找歌曲，并可按艺人缩小范围。

参数	类型	必填	功能说明
title	string，1 到 120 个字符	是	歌曲标题或标题片段。
artist	string，最多 120 个字符	否	仅保留标注为该艺人的歌曲。
limit	integer，1 到 50，默认值为 10	否	返回的行数。
page	integer，1 到 20，默认值为 1	否	返回哪一页结果。
match	loose 或 strict，默认值为 loose	否	艺人名称需要匹配得多严格。

返回内容： 返回 search_lyrics 所提供的结果行，其中 artist_filter 会复述请求的筛选条件，filtered_out 则统计因艺人限制而移除的结果数。strict 仅保留名称与输入完全一致的艺人；loose 则接受写法不同的名称。

get_lyrics

读取一首歌曲的歌词。较长的歌词会分段提供。

参数	类型	必填	作用
id	字符串	二选一	搜索结果行中包含的歌曲 ID。
url	lyrics.com URL	二选一	歌曲页面的地址。
max_chars	整数，200 到 20000，默认值为 6000	否	此次调用要提供的文本字符数。
offset	整数，0 或更大，默认值为 0	否	恢复读取时使用的字符偏移量。
highlight	字符串，最多 120 个字符	否	要在文本中查找的词语。

返回内容：status，读取状态；如果网站上的页面没有歌词，则为 ok 或 no_lyrics；title、artist 和 source_url；以及歌词片段本身 lyrics。 读取情况由 total_chars、returned_chars、offset、next_offset 和 truncated 描述；将 next_offset 传回即可继续读取，其中 null 表示已到末尾。line_count 统计片段中的行数；highlight 会针对每个词语 返回其是否 found，以及所在的 line_number；如果未找到，则为 null。

配置

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

变量	默认值	作用
LYRICSCOM_USER_AGENT	项目标识	向网站标识你的应用，并提供可联系到相关人员的地址。
LYRICSCOM_MIN_INTERVAL_MS	1100	两次请求之间的间隔，范围为 500 到 60000。
LYRICSCOM_TIMEOUT_MS	15000	单次请求的时限，范围为 1000 到 120000。
LYRICSCOM_MAX_RETRIES	3	临时故障后的重试次数，范围为 0 到 10。
LYRICSCOM_CACHE_TTL_MS	900000	答案在内存中的保留时长，范围为 0 到 86400000。
LYRICSCOM_CACHE_MAX_ENTRIES	200	同时保存在内存中的答案数量，范围为 0 到 10000。
LYRICSCOM_LOG_LEVEL	error	日志级别，可选 silent、error、info 或 debug；日志写入 stderr。

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

关于 User-Agent。 此服务会标识项目并链接到其代码仓库，网站会显示这些信息。 网站确实会直接拒绝某些通用工具 Agent：普通的 curl 会收到 403。 blocked_user_agent 错误表示身份标识被拒绝，你可以通过 LYRICSCOM_USER_AGENT 设置自选标识。如何填写由你决定，并由你自行负责。

错误

每次失败都会附带以下错误代码之一、一条消息，以及在有帮助时说明下一步操作的提示。

代码	发生了什么	如何处理
not_found	网站已响应，但没有这首歌。	使用 search_songs 检查 ID。
invalid_input	请求发出前，参数就被拒绝了。	阅读消息，其中会指出具体参数。
throttled	网站要求此客户端减慢请求速度。	等待一会儿，然后使用相同参数再次调用。这首歌仍然存在。
blocked_user_agent	网站拒绝了此客户端发送的身份标识。	设置 LYRICSCOM_USER_AGENT。
parse_failure	页面已加载，但预期内容不存在。	在问题跟踪器中报告。
network_error	请求未能完成。	稍后重试。
timeout	请求超时。	增大 LYRICSCOM_TIMEOUT_MS，或请求较小的 max_chars。

throttled 和 blocked_user_agent 是此服务表示拒绝提供服务的两种错误代码；调用方读取多个来源时，会将它们统一归为其所称的速率限制。

作为库使用

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

import { LyricsComClient } from "mcp-lyricscom/client";

const client = new LyricsComClient();
const { data, cached } = await client.getSong({ id: "1234567" });
console.log(data.title, data.artist, cached);

search 和 getSong 都会返回 { data, cached }，并抛出携带上述错误代码之一的错误。这里同样会确保两次请求之间至少间隔规定的时间。

请求间隔与署名

请求会逐个发送，且间隔至少一秒；无论服务如何配置，两次请求之间都会至少间隔半秒。verify: "full" 搜索最多会获取五个歌曲页面，这是此服务中开销最大的操作。

每个结果都包含艺人、标题和歌曲页面地址。歌曲歌词由其作者和出版商创作。本项目不主张拥有这些歌词的任何权利，不附带歌词数据库，也不会将任何内容写入磁盘。

此 MCP 服务是一个非官方项目，与 lyrics.com 没有任何关联。

隐私

此服务不会收集任何关于你的信息，也不会向其作者发送任何内容。它在你的机器上运行，只会连接 www.lyrics.com，运行期间将结果保存在内存中，不会将任何内容写入磁盘。 PRIVACY.md 说明了请求会携带哪些信息，以及哪些设置会影响这些信息。

开发

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

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

贡献

Bug、问题和想法请提交到 问题跟踪器。欢迎提交拉取请求；先创建问题有助于商定变更方案。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。歌词归其作者和出版商所有。

---

mcp-lyricscom（法语）

English version

lyrics.com 是一个大型的公开歌词目录。它会按歌曲标题、艺人、发行专辑和年份对歌曲进行分类，并收录歌词原文。它支持在歌词内容中搜索。

此服务将对话客户端连接到该目录。你可以根据记得的歌词搜索歌曲，按标题和艺人搜索，也可以分段阅读歌曲歌词，并在文本中定位搜索词。无需 API 密钥，也无需账号。

安装

一键安装

Claude Code

claude mcp add lyricscom -- npx -y mcp-lyricscom

Claude Desktop、Cursor，以及所有采用标准配置格式的客户端

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

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

使用 Docker

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

-i 会让标准输入保持打开，这是协议通信通道；省略 -t 是因为 TTY 会改写数据流。容器只需能通过 HTTPS 访问 www.lyrics.com，不需要其他配置：无需卷、无需端口、无需凭据。

Bundle，无需 npm

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

可以提出哪些请求

• “哪首歌里有‘I’ve got a hand for you’这句歌词？”
• “帮我找一下 Glen Campbell 演唱的 Wichita Lineman 的歌词。”
• “读一下这段歌词的后半部分。”
• “这首歌里‘lineman’一词出现在哪里？”
• “这首歌收录在哪些专辑中？”

通常的流程是先搜索再阅读：某一行会提供一个 id，然后 get_lyrics 会使用这个标识符。

工具

工具	功能
search_lyrics	根据歌词中的某一句查找歌曲。
search_songs	按标题查找歌曲，并可按艺人缩小范围。
get_lyrics	分段读取歌曲歌词。

search_lyrics

根据歌词中的词句查找歌曲。该网站的排序较宽泛，因此会在返回结果前验证匹配项。

参数	类型	必填	作用
query	字符串，1 至 120 个字符	是	要搜索的歌词句子或其中一部分。
limit	整数，1 至 50，默认值为 10	否	返回的行数。
page	整数，1 至 20，默认值为 1	否	返回第几页。
verify	snippet、full 或 none，默认值为 snippet	否	如何确认歌词中包含这些词句。
include_excerpt	布尔值，默认值为 true	否	在每一行中附上匹配的歌词句子。

verify 决定一行结果是否有效。snippet 会验证网站已返回的摘录，不会产生额外开销。full 最多获取五页歌曲并验证完整歌词；此方式较慢，也可能触发限流。none 则直接返回网站排序后的结果，不进行验证。

**返回：**包含 id 的行，可供 get_lyrics 使用；以及 title、artist、album 和 year（目录未提供信息时为 null）、source_url 和匹配的歌词句子 excerpt。raw_result_count 表示网站返回的行数，filtered_out 表示验证时移除的行数；两者结合可反映排序结果的宽泛程度。可通过 has_more 和 next_page 继续获取结果。

search_songs

按标题查找歌曲，并可按艺术家缩小范围。

参数	类型	必填	作用
title	字符串，1 至 120 个字符	是	歌曲标题或其中一部分。
artist	字符串，最多 120 个字符	否	仅保留该艺术家的歌曲。
limit	整数，1 至 50，默认值为 10	否	返回的行数。
page	整数，1 至 20，默认值为 1	否	返回第几页。
match	loose 或 strict，默认值为 loose	否	艺术家匹配的严格程度。

**返回：**与 search_lyrics 返回的行相同，另含 artist_filter（回显请求的筛选条件）和 filtered_out（因艺术家筛选而移除的行数）。strict 仅保留名称与输入完全匹配的艺术家；loose 则接受名称写法不同的艺术家。

get_lyrics

读取歌曲歌词。较长的歌词会分段提供。

参数	类型	必填	作用
id	字符串	二选一	歌词行所带的标识符。
url	lyrics.com 地址	二选一	歌曲页面的地址。
max_chars	整数，200 到 20000，默认值为 6000	否	本次调用提供的文本字符数。
offset	整数，0 或更大，默认值为 0	否	继续读取的字符位置。
highlight	字符串，最多 120 个字符	否	要在文本中查找的词语。

返回内容： status，取值为 ok 或 no_lyrics，后者表示网站上有该页面但没有歌词；title、artist 和 source_url；以及 lyrics，即当前返回的片段。读取信息由 total_chars、returned_chars、offset、next_offset 和 truncated 描述：提供 next_offset 即可继续读取，null 表示已到末尾。line_count 统计当前片段的行数；highlight 会针对每个词说明是否 found，以及对应的 line_number；未找到时为 null。

配置

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

变量	默认值	作用
LYRICSCOM_USER_AGENT	项目标识	向网站标识您的应用，并提供可联系人员的地址。
LYRICSCOM_MIN_INTERVAL_MS	1100	两次请求之间的间隔，范围为 500 到 60000。
LYRICSCOM_TIMEOUT_MS	15000	请求超时时间，范围为 1000 到 120000。
LYRICSCOM_MAX_RETRIES	3	临时失败后的重试次数，范围为 0 到 10。
LYRICSCOM_CACHE_TTL_MS	900000	响应在内存中的保留时长，范围为 0 到 86400000。
LYRICSCOM_CACHE_MAX_ENTRIES	200	同时保留在内存中的响应数量，范围为 0 到 10000。
LYRICSCOM_LOG_LEVEL	error	silent、error、info 或 debug，日志写入错误输出。

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

关于 User-Agent。 此服务会标识项目并指向其代码库，网站允许此类请求。但网站会拒绝某些通用工具的 User-Agent：直接使用 curl 会收到 403 错误。blocked_user_agent 错误表示发送的标识遭到拒绝；您可以通过 LYRICSCOM_USER_AGENT 设置自选标识。对此处填写的内容，您需自行决定并承担相应责任。

错误

每次失败都会带有以下代码之一、一条消息，以及在有帮助时给出下一步操作提示。

代码	发生了什么	该怎么做
not_found	网站已响应，但没有这首歌。	使用 search_songs 检查标识符。
invalid_input	参数在发出任何请求前就被拒绝了。	阅读消息，其中会指出相关参数。
throttled	网站要求此客户端放慢速度。	等一会儿，然后使用相同参数重试。这首歌仍然存在。
blocked_user_agent	网站拒绝了此客户端发送的身份信息。	设置 LYRICSCOM_USER_AGENT。
parse_failure	页面已加载，但缺少预期内容。	在问题跟踪页报告此问题。
network_error	请求未能完成。	稍后重试。
timeout	请求超时。	增大 LYRICSCOM_TIMEOUT_MS，或请求较小的 max_chars。

throttled 和 blocked_user_agent 是此服务用来表示拒绝提供服务的两个名称；读取多个来源的调用方会将它们归为其所称的速率限制。

作为库使用

读取网站的这一层单独发布，包含自身的速率控制、缓存和错误处理，不绑定任何协议。

import { LyricsComClient } from "mcp-lyricscom/client";

const client = new LyricsComClient();
const { data, cached } = await client.getSong({ id: "1234567" });
console.log(data.title, data.artist, cached);

search 和 getSong 均会返回 { data, cached }，并抛出带有上述代码之一的错误。两次请求之间的最小间隔在这里同样适用。

速率控制与署名

请求会逐个发出，且间隔至少一秒；无论如何配置，最小间隔都为半秒。使用 verify: "full" 的搜索最多会查询五个歌曲页面，这是此服务执行的成本最高的操作。

每个结果都包含艺术家、标题和歌曲页面地址。歌词属于其作者和出版商。本项目不主张拥有歌词的任何权利，不收录任何歌词数据库，也不会向磁盘写入任何内容。

此 MCP 是一个非官方项目，与 lyrics.com 无关联。

隐私

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

开发

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

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

贡献

问题、疑问和想法都可以在问题跟踪页提出。欢迎提交修改建议；先创建工单有助于就修改形式达成一致。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。歌词属于其作者和出版商。