setlist-mcp

一个 MCP 服务器，让 Claude 可以查找你去过的演出的 setlist.fm 歌单。

问“我1992年8月在惠灵顿看了The Cure的演出—他们演了什么？”Claude 会解析艺人，搜索 setlist.fm，并按顺序读出歌曲。

功能

• find_setlists — 按艺人、城市和日期搜索。返回匹配演出的紧凑列表，包含歌单 ID、场馆和歌曲数量。

• get_setlist — 获取一个完整的歌单：按顺序列出每首歌，按部分和返场分组，并附有翻唱和嘉宾出场说明。

• 对日期宽容。 搜索会覆盖你给出的日期前后一年，并按接近程度对结果排序，所以即使记错了日子也能找到演出。

• 对艺人名字宽容。 名字通过 MusicBrainz 解析，所以轻微拼写错误通常仍能生效。有歧义的名字会返回备选方案。

• 谨慎处理速率限制。 请求被串行化并间隔发送，429 错误会以退避方式重试，响应会被缓存。搜索按设计需要几秒钟。

Related MCP server: MusicBrainz MCP Server

安装

git clone git@github.com:adrianparker/setlist-mcp.git
cd setlist-mcp
npm install
cp .env.example .env

然后编辑 .env 并设置 SETLISTFM_API_KEY。在 setlist.fm 的 API 设置 申请一个密钥—它是免费的，并且需要一个 setlist.fm 账户。

将 MUSICBRAINZ_CONTACT 设置为你的电子邮件地址是一种礼貌：MusicBrainz 要求客户端在其 User-Agent 中标识一个联系人，并且会对看起来匿名的客户端进行更严格的限流。

注册到 Claude Code

claude mcp add setlist-mcp --scope user -- node /full/path/to/setlist-mcp/src/index.js

或者将其添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "setlist-mcp": {
      "command": "node",
      "args": ["/full/path/to/setlist-mcp/src/index.js"]
    }
  }
}

客户端配置中不包含任何机密—服务器从自己的目录读取 .env，因此无论客户端从哪个目录启动它都能正常工作。

重启 Claude Code，然后用 /mcp 检查它是否已连接。

用法

注册完成后，直接用简单的英语提问：

我2026年3月在陶朗加看了Villainy的演出，歌单是什么？

Claude 会调用 find_setlists，选择匹配的演出，然后调用 get_setlist。

要在没有客户端的情况下直接检查服务器：

npx @modelcontextprotocol/inspector node src/index.js

配置

速率限制

setlist.fm 没有公布其速率限制。社区报告称标准层级约为每秒 2 个请求、每天 1440 个请求，因此这里的默认值—每 1.1 秒一个请求—舒适地处于较慢的一端。请求通过队列串行化，因此并发的工具调用会排队等待，而不是突发。429 会让整个队列退避，并在服务器发送 Retry-After 时予以遵守。

每日限制并不是真正的每日配额。 它保存在内存中，因此每当 MCP 客户端重启服务器时它就会重置。请将其视为针对失控循环的断路器，而不是合规措施。真正保护你的密钥的是最小间隔：按每请求 1.1 秒计算，达到 1440 个请求需要连续查询 26 分钟。

响应缓存在内存中—艺人 24 小时、搜索 1 小时、歌单详情 6 小时—因此重复询问同一场演出不会产生任何成本。

开发

运行测试

npm test
npm run test:watch

没有测试会触及真实 API：test/setup.js 安装了一个会抛错的 global.fetch，测试会显式地对其进行桩替换。

覆盖率

npm run coverage

代码检查

npm run lint

关于 setlist.fm 的说明

setlist.fm API 仅限非商业用途免费使用—请参阅他们的 API 条款。两个工具都会为每个结果返回 setlist.fm URL，以便可以链接回去。

歌单数据由 setlist.fm 的用户贡献。演出可能缺失、不完整，或者日期有误。

许可证

MIT