kofic-mcp-server

영화진흥위원회(KOFIC) 박스오피스 오픈API를 감싼 MCP 서버. Vercel에 배포해서 Claude의 커스텀 커넥터로 연결하는 것을 목표로 합니다.

1. 로컬 설정

npm install
cp .env.example .env.local
# .env.local 에 KOFIC_API_KEY 입력
npm run dev

로컬에서 http://localhost:3000/mcp 로 MCP 엔드포인트가 뜹니다. MCP Inspector로 테스트해보세요:

npx @modelcontextprotocol/inspector@latest

Inspector에서 Transport를 Streamable HTTP로 두고 위 URL을 입력하면 tool 목록(get_daily_boxoffice, get_weekly_boxoffice, search_movie, get_movie_info)이 보이고, 직접 호출해서 KOFIC 응답이 제대로 오는지 확인할 수 있습니다.

2. Vercel 배포

npx vercel

배포 후 Vercel 프로젝트 Settings > Environment Variables 에서 KOFIC_API_KEY 를 등록하고 재배포하세요 (npx vercel --prod).

3. Claude에 연결

1. claude.ai → Settings → Connectors → Add custom connector
2. URL에 https://<your-project>.vercel.app/mcp 입력
3. 대화(프로젝트 포함)에서 "+" 메뉴로 커넥터를 켠 뒤 사용

현재 제공 tool

• get_daily_boxoffice(targetDt, itemPerPage?) — 일별 박스오피스 + 그 시점 누적관객수
• get_weekly_boxoffice(targetDt, weekGb?) — 주간/주말/주중 박스오피스
• search_movie(movieNm) — 영화명으로 movieCd 검색
• get_movie_info(movieCd) — 개봉일/감독/배우 등 상세정보

다음 단계 (아직 미구현)

• Day14 / Day49 누적관객수 자동 수집 (개봉일 기준 날짜 계산 + 여러 날짜 순회 조회)
• 2주차 드롭율, 뒷심 배수(Day49/Day14) 계산 로직
• 4분면 포지셔닝 분류 tool (classify_boxoffice_pattern 같은 이름으로 추가 예정)