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

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

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

- "어제 박스오피스 1~10위 알려줘"
- "지난주 주말 한국영화 박스오피스는?"
- "봉준호 감독 영화 목록 보여줘"
- "기생충 상영시간이랑 출연 배우 알려줘"
- "서울 지역 일별 박스오피스는?"

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

## 도구

| 도구 | 하는 일 | 주요 인자 |
|---|---|---|
| `get_daily_box_office` | 일별 박스오피스 | `target_date` (기본: 어제), `items` (1~10), `movie_type` (`all`/`diversity`/`commercial`), `nation` (`all`/`korean`/`foreign`), `area_code` |
| `get_weekly_box_office` | 주간·주말 박스오피스 | `target_date` (기본: 7일 전), `week_type` (`weekly` 월~일 / `weekend` 금~일 / `weekdays` 월~목), 나머지는 일별과 같음 |
| `search_movies` | 영화 검색 | `movie_name`, `director_name`, `open_start_year`/`open_end_year`, `production_start_year`/`production_end_year`, `nation_code`, `movie_type_codes`, `page`, `per_page` |
| `get_movie_info` | 영화 상세 (상영시간, 장르, 감독, 배우, 관람등급, 제작·배급사) | `movie_cd` |
| `search_people` | 영화인 검색 | `name`, `filmography`, `page`, `per_page` |
| `get_person_info` | 영화인 상세 (필모그래피) | `people_cd` |
| `search_companies` | 영화사 검색 | `company_name`, `ceo_name`, `part_code`, `page`, `per_page` |
| `get_company_info` | 영화사 상세 | `company_cd` |
| `get_code_list` | 공통코드 조회 (지역·국적·영화유형 코드 찾기) | `com_code` — 예: `0105000000` 광역지역, `2204` 국적, `2201` 영화유형 |

- 모든 도구는 읽기 전용입니다 (`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` 등).

## 1. API 키 발급

1. <https://www.kobis.or.kr/kobisopenapi> 에 접속해 회원가입·로그인합니다.
2. **키 발급/관리** 메뉴에서 키를 발급받습니다 (무료, 기본 하루 3,000회 호출).

## 2. 설치

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

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

[uv](https://docs.astral.sh/uv/)가 있으면 저장소를 내려받지 않아도 됩니다.

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

### 방법 B: 저장소 클론

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

```bash
# 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`에 들어 있어 커밋되지 않습니다.

```bash
cp .env.example .env
```

```dotenv
KOBIS_API_KEY=발급받은_키
```

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

## 4. MCP 클라이언트에 연결

### Claude Desktop

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

uvx 사용 시:

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

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

```json
{
  "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

```bash
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로 실행

```bash
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 클라이언트를 재시작하세요.
```

| 코드 | 뜻 |
|---|---|
| `CONFIG_ERROR` | API 키가 설정되지 않음 |
| `AUTH_ERROR` | 키가 틀렸거나 하루 호출 한도 초과 (KOBIS 오류 320010 등) |
| `INVALID_PARAMETER` | 날짜·코드 등 인자 형식 오류 |
| `NOT_FOUND` | 코드에 해당하는 영화·영화인·영화사가 없음 |
| `UPSTREAM_ERROR` | KOBIS 서버 장애. **대상이 없다는 뜻이 아닙니다** |

- 네트워크 오류와 5xx 응답은 최대 3번까지 재시도합니다.
- 같은 요청은 10분 동안 캐시해서 하루 호출 한도를 아낍니다.
- API 키는 에러 메시지와 로그에 남기지 않습니다.

## 개발

```bash
pip install -e ".[dev]"
pytest
```

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

## 데이터 출처와 이용 조건

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

## 라이선스

[MIT](LICENSE)