setlist-mcp

MCP-сервер, который позволяет Claude находить сетлисты с setlist.fm для концертов, на которых вы были.

Спросите «Я видел The Cure в Веллингтоне в августе 1992 года — что они играли?» — и 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. Запросите ключ в настройках API setlist.fm — это бесплатно и требует учётной записи 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.

Использование

После регистрации просто спросите на обычном английском:

Я видел Villainy в Тауранге в марте 2026 года, какой был сетлист?

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

API setlist.fm бесплатен только для некоммерческого использования — см. их условия использования API. Оба инструмента возвращают URL setlist.fm для каждого результата, чтобы можно было поставить ссылку.

Данные сетлистов предоставляются пользователями setlist.fm. Концерты могут отсутствовать, быть неполными или иметь неверную дату.

Лицензия

MIT