setlist-mcp

Claude가 다녀온 공연의 setlist.fm 세트리스트를 찾을 수 있게 해주는 MCP 서버입니다.

"1992년 8월 웰링턴에서 The Cure 공연을 봤는데, 그때 뭐를 연주했지?"라고 물어보면 Claude가 아티스트를 확인하고, setlist.fm을 검색한 뒤, 곡들을 순서대로 읽어줍니다.

기능

• find_setlists — 아티스트, 도시, 날짜로 검색합니다. 일치하는 공연의 세트리스트 ID, 공연장, 곡 수를 포함한 간결한 목록을 반환합니다.

• get_setlist — 하나의 세트리스트를 전체로 가져옵니다: 모든 곡을 순서대로, 세트와 앵콜로 그룹화하고, 커버 및 게스트 출연 정보를 포함합니다.

• 날짜에 관대합니다. 검색은 입력한 날짜를 기준으로 전후 1년을 포함하며, 날짜가 가까운 순서대로 결과를 정렬하므로 날짜를 잘못 기억해도 공연을 찾을 수 있습니다.

• 아티스트 이름에 관대합니다. 이름은 MusicBrainz를 통해 확인되므로, 사소한 오타도 대개는 작동합니다. 모호한 이름은 대안과 함께 반환됩니다.

• 속도 제한에 주의합니다. 요청은 직렬화되고 간격을 두고 전송되며, 429 응답은 백오프로 재시도되고, 응답은 캐시됩니다. 검색은 의도적으로 몇 초가 걸립니다.

Related MCP server: Last.fm 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초에 1회 요청 — 은 그보다 느린 쪽에 안전하게 위치합니다. 요청은 큐를 통해 직렬화되므로, 동시 도구 호출은 폭주하지 않고 차례를 기다립니다. 429 응답이 오면 전체 큐가 백오프되며, 서버가 보내는 Retry-After를 존중합니다.

일일 한도는 실제 일일 할당량이 아닙니다. 메모리에 저장되므로, MCP 클라이언트가 서버를 재시작할 때마다 초기화됩니다. 이를 규정 준수가 아닌, 통제 불능 루프에 대한 회로 차단기로 취급하세요. 실제로 키를 보호하는 것은 최소 간격입니다: 1.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