한국에서 열리는 공연 정보는 사실 한곳에 모여 있어요. KOPIS(공연예술통합전산망)라는 공공 데이터베이스요. 문제는 이걸 코드로 꺼내 쓰려면 XML 응답을 파싱하고, 파라미터 이름을 문서에서 찾아가며 맞춰야 한다는 거예요. 한 번 해보면 알아요. 되긴 되는데, 손이 많이 가요.
그래서 그 번거로움을 한 겹 걷어낸 도구를 만들었어요. @coldsurf/tickets. npm에 공개돼 있고 MIT 라이선스예요. 쓰는 방법은 세 가지 — 터미널에서, 코드에서, 그리고 AI한테 말로.
먼저 준비물 하나. KOPIS OpenAPI 키가 필요해요. kopis.or.kr에서 무료로 발급받아, 환경변수로 넣어두면 돼요.
export KOPIS_KEY="발급받은_키"이제 세 가지를 차례로 볼게요.
1. 터미널에서 — 설치도 필요 없어요
가장 빠른 건 CLI예요. 설치할 것도 없이 npx로 바로 돌려요.
npx @coldsurf/tickets find --startDate 20260714 --venue "예스24 라이브홀"그러면 결과가 표로 딱 떨어져요. 공연명, 기간, 공연장, 상태까지요. --format json을 붙이면 JSON으로 나오고요. 목록만이 아니라 공연 상세, 공연장 검색, 기획사, 수상작, 축제까지 조회할 수 있어요.
npx @coldsurf/tickets venue --name "예스24" # 공연장 검색
npx @coldsurf/tickets detail PF123456 # 공연 상세
npx @coldsurf/tickets find --startDate 20260714 --category GGGA --area 11 # 서울 뮤지컬만빠르게 뭐 하나 확인하고 싶을 때 제일 편해요.
2. 코드에서 — 타입 안전한 SDK로
프로젝트 안에서 쓸 거면 SDK로 import해요. 응답이 이미 깔끔한 타입으로 정리돼 있어서, XML을 만질 일이 없어요.
import { createKopisClient } from '@coldsurf/tickets'
const client = createKopisClient(process.env.KOPIS_KEY!)
const shows = await client.getPerformanceList({
startDate: '20260714',
venue: '예스24 라이브홀',
})
// shows: { title, startDate, endDate, venue, genre, state, ... }[]getPerformanceList 말고도 getVenueList, getPerformanceDetail, getFestivalList 같은 메서드가 8개 있어요. 전부 타입이 붙어 있어서, 에디터가 필드를 다 알려줘요. 파라미터 이름을 외울 필요가 없죠.
3. AI한테 — 말로 물어봐요 (MCP)
이번에 새로 붙인 게 이거예요. MCP(Model Context Protocol) 서버요. Claude 같은 AI 호스트에 등록해두면, 플래그도 메서드도 필요 없이 그냥 말로 물어봐요.
설정은 호스트의 mcpServers에 이 한 조각을 넣으면 끝이에요.
{
"mcpServers": {
"tickets": {
"command": "npx",
"args": ["-y", "-p", "@coldsurf/tickets", "tickets-mcp"],
"env": { "KOPIS_KEY": "발급받은_키" }
}
}
}Claude Code를 쓴다면 한 줄로도 돼요.
claude mcp add tickets --env KOPIS_KEY=발급받은_키 -- npx -y -p @coldsurf/tickets tickets-mcp이제 그냥 이렇게 물어요.
"오늘 예스24라이브홀 공연 알려줘"
그러면 AI가 알아서 도구를 골라 KOPIS를 조회하고 답을 줘요. "오늘"은 오늘 날짜로, "예스24라이브홀"은 공연장 자리로 — 문장을 인자로 바꾸는 건 AI가 다 해줘요. 실제로 물어보면 이렇게 와요.
이번 달 "예스24" 공연 5건
- 승리의 여신: 니케, 밴드라이브 콘서트 | 07.18~19 | 예스24 라이브홀
- V$ X V PRiNCE & LUCAVEROS | 08.01 | 예스24 라이브홀
…
목록만이 아니라 "이 공연 러닝타임 얼마야?", "홍대 근처 이번 주 공연 뭐 있어?" 같은 것도 이어서 물어볼 수 있고요.
왜 만들었냐면
COLDSURF가 하려는 일은 결국 흩어진 공연 정보를 발견하기 쉽게 만드는 거예요. 그 출발점이 데이터를 손쉽게 꺼내 쓰는 거고요. 이 도구는 그 바닥 레이어예요 — 나중에 뭘 만들든 공연 데이터를 꺼내는 부분은 이거 하나로 끝나게, 재사용할 수 있게 떼어둔 조각이에요.
오픈소스라 누구나 써도 돼요. 공연 정보를 다루는 사이드 프로젝트가 있다면, 아니면 그냥 "오늘 무슨 공연 있지?"가 궁금하다면 한 번 써보세요.
npx @coldsurf/tickets find --startDate 20260714이 한 줄이면 시작이에요.