kobis-mcp — 영화진흥위원회(KOBIS) 오픈 API MCP 서버

영화진흥위원회 영화관입장권 통합전산망(KOBIS) 오픈 API를 Claude, Cursor 같은 MCP 클라이언트에서 쓸 수 있게 해 주는 MCP 서버입니다. FastMCP로 만들었습니다.

연결하면 이런 질문에 실제 집계 데이터로 답합니다.

• "어제 박스오피스 1~10위 알려줘"

• "지난주 주말 한국영화 박스오피스는?"

• "봉준호 감독 영화 목록 보여줘"

• "기생충 상영시간이랑 출연 배우 알려줘"

• "서울 지역 일별 박스오피스는?"

API 키는 이 저장소에 들어 있지 않습니다. 각자 KOBIS에서 무료로 키를 발급받아 자신의 MCP 클라이언트 설정이나 .env 파일에 넣어야 합니다.

도구

• 모든 도구는 읽기 전용입니다 (readOnlyHint).

• 날짜는 20261113, 2026-11-13 둘 다 됩니다. 일별 박스오피스는 어제까지만 집계됩니다.

• 상세 조회는 검색 → 코드 → 상세 순서입니다. 예: search_movies("기생충") → movie_cd → get_movie_info(movie_cd).

• 박스오피스 결과는 숫자를 정수로 바꾸고 키를 읽기 쉽게 정리합니다 (audience, audience_total, sales, sales_share_pct, rank_change, is_new 등).

Related MCP server: kosis-mcp

1. API 키 발급

1. https://www.kobis.or.kr/kobisopenapi 에 접속해 회원가입·로그인합니다.

2. 키 발급/관리 메뉴에서 키를 발급받습니다 (무료, 기본 하루 3,000회 호출).

2. 설치

Python 3.10 이상이 필요합니다. 둘 중 편한 방법을 고르세요.

방법 A: uvx로 바로 실행 (설치 없이)

uv가 있으면 저장소를 내려받지 않아도 됩니다.

uvx --from git+https://github.com/myungwoon/kobis-mcp kobis-mcp

방법 B: 저장소 클론

git clone https://github.com/myungwoon/kobis-mcp.git
cd kobis-mcp
python -m venv .venv

# Windows
.venv\Scripts\pip install -e .
# macOS / Linux
.venv/bin/pip install -e .

3. API 키 설정

서버는 아래 순서로 KOBIS_API_KEY를 찾고, 먼저 찾은 값을 씁니다.

1. 환경변수 KOBIS_API_KEY — MCP 클라이언트 설정의 env 블록에 넣는 방법 (권장)

2. KOBIS_ENV_FILE 환경변수 또는 --env-file 옵션이 가리키는 .env 파일

3. 서버를 실행한 작업 디렉터리(또는 상위)의 .env

4. 저장소 루트의 .env (방법 B로 클론한 경우)

.env를 쓰려면 예시 파일을 복사해 값을 채웁니다. .env는 .gitignore에 들어 있어 커밋되지 않습니다.

cp .env.example .env

KOBIS_API_KEY=발급받은_키

키 없이도 서버는 뜨지만, 도구를 호출하면 [CONFIG_ERROR]와 설정 방법을 돌려줍니다.

4. MCP 클라이언트에 연결

Claude Desktop

claude_desktop_config.json (Windows: %APPDATA%\Claude\, macOS: ~/Library/Application Support/Claude/)에 추가합니다.

uvx 사용 시:

{
  "mcpServers": {
    "kobis": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/myungwoon/kobis-mcp", "kobis-mcp"],
      "env": { "KOBIS_API_KEY": "발급받은_키" }
    }
  }
}

클론한 경우 (경로는 자신의 위치로 바꾸세요):

{
  "mcpServers": {
    "kobis": {
      "command": "C:\\path\\to\\kobis-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\kobis-mcp\\server.py"],
      "env": { "KOBIS_API_KEY": "발급받은_키" }
    }
  }
}

클론한 경우 env 블록 대신 저장소 루트의 .env에 키를 넣어도 됩니다.

Claude Code

claude mcp add kobis -e KOBIS_API_KEY=발급받은_키 -- uvx --from git+https://github.com/myungwoon/kobis-mcp kobis-mcp

Cursor 등 다른 클라이언트

command/args/env 형식은 위 Claude Desktop 예시와 같습니다. 클라이언트의 MCP 설정 파일(예: Cursor는 ~/.cursor/mcp.json)에 넣으세요.

HTTP로 실행

kobis-mcp --transport http --port 8000   # http://127.0.0.1:8000/mcp

기본은 로컬(127.0.0.1)에만 바인드합니다. 인증 기능이 없으므로 외부에 공개하려면 앞단에 인증 프록시를 두세요.

응답과 에러

실패하면 첫 줄이 대괄호 코드로 시작하고, 다음에 해볼 일을 번호로 붙입니다.

[CONFIG_ERROR] KOBIS API 키가 설정되지 않았습니다 (환경변수 KOBIS_API_KEY).
제안:
  1. https://www.kobis.or.kr/kobisopenapi 에서 키를 발급받으세요.
  2. MCP 클라이언트 설정의 "env" 에 "KOBIS_API_KEY": "발급받은키" 를 추가하거나, .env 파일에 KOBIS_API_KEY=발급받은키 를 적으세요.
  3. 설정 후 MCP 클라이언트를 재시작하세요.

• 네트워크 오류와 5xx 응답은 최대 3번까지 재시도합니다.

• 같은 요청은 10분 동안 캐시해서 하루 호출 한도를 아낍니다.

• API 키는 에러 메시지와 로그에 남기지 않습니다.

개발

pip install -e ".[dev]"
pytest

테스트는 KOBIS API를 목킹하므로 키 없이 돌아갑니다.

데이터 출처와 이용 조건

모든 데이터는 영화진흥위원회 KOBIS 오픈 API에서 옵니다. 데이터 이용 시 KOBIS 오픈 API 이용약관을 따르고 출처를 표기하세요. 이 프로젝트는 영화진흥위원회와 관련이 없는 비공식 도구입니다.

라이선스

MIT