Skip to main content
Glama
README.md
# 🎬 KOBIS MCP Server

[μ˜ν™”μ§„ν₯μœ„μ›νšŒ μ˜ν™”κ΄€μž…μž₯ꢌ 톡합전산망(KOBIS) μ˜€ν”ˆAPI](https://www.kobis.or.kr/kobisopenapi)λ₯Ό Claude 같은 AI λ„κ΅¬μ—μ„œ μ“Έ 수 있게 ν•΄μ£ΌλŠ” **MCP μ„œλ²„**μž…λ‹ˆλ‹€.

μ—°κ²°ν•˜λ©΄ AIμ—κ²Œ μ΄λ ‡κ²Œ λ¬Όμ–΄λ³Ό 수 μžˆμŠ΅λ‹ˆλ‹€.

- "μ–΄μ œ λ°•μŠ€μ˜€ν”ΌμŠ€ 1~10μœ„ μ•Œλ €μ€˜"
- "μ§€λ‚œ 주말 ν•œκ΅­ μ˜ν™” μˆœμœ„λ§Œ λ³΄μ—¬μ€˜"
- "λ΄‰μ€€ν˜Έ 감독 μ˜ν™” λͺ©λ‘μ΄λž‘ 각 μ˜ν™” κ΄€λžŒλ“±κΈ‰ μ •λ¦¬ν•΄μ€˜"
- "'μ„œμšΈμ˜ λ΄„' μΆœμ—° λ°°μš°μ™€ μƒμ˜μ‹œκ°„ μ•Œλ €μ€˜"

> **API ν‚€λŠ” 이 μ½”λ“œμ— λ“€μ–΄μžˆμ§€ μ•ŠμŠ΅λ‹ˆλ‹€.** 각자 λ°œκΈ‰λ°›μ€ ν‚€λ₯Ό λ‚΄ 컴퓨터 섀정에 λ„£μ–΄μ„œ μ‚¬μš©ν•©λ‹ˆλ‹€.

---

## 1. API ν‚€ λ°œκΈ‰λ°›κΈ° (무료)

1. [KOBIS μ˜€ν”ˆAPI](https://www.kobis.or.kr/kobisopenapi) 접속 ν›„ νšŒμ›κ°€μž… 및 둜그인
2. 상단 메뉴 **ν‚€ λ°œκΈ‰/관리** β†’ **ν‚€ λ°œκΈ‰**
3. λ°œκΈ‰λœ ν‚€(영문+숫자 32자리)λ₯Ό 볡사해 λ‘‘λ‹ˆλ‹€.

## 2. μ„€μΉ˜ 및 μ—°κ²°

[Node.js](https://nodejs.org) 18 이상이 ν•„μš”ν•©λ‹ˆλ‹€. ν„°λ―Έλ„μ—μ„œ `node -v`둜 확인할 수 μžˆμŠ΅λ‹ˆλ‹€.
λ”°λ‘œ 내렀받을 ν•„μš” 없이, μ•„λž˜ μ„€μ •λ§Œ λ„£μœΌλ©΄ GitHubμ—μ„œ μžλ™μœΌλ‘œ λ°›μ•„ μ‹€ν–‰λ©λ‹ˆλ‹€.

### Claude Desktop

`μ„€μ • β†’ 개발자 β†’ ꡬ성 νŽΈμ§‘`을 눌러 `claude_desktop_config.json`을 μ—΄κ³  μ•„λž˜ λ‚΄μš©μ„ μΆ”κ°€ν•©λ‹ˆλ‹€.

```json
{
  "mcpServers": {
    "kobis": {
      "command": "npx",
      "args": ["-y", "github:cocossi381-cell/kobis-mcp"],
      "env": {
        "KOBIS_API_KEY": "여기에_λ°œκΈ‰λ°›μ€_ν‚€"
      }
    }
  }
}
```

μ €μž₯ν•œ λ’€ Claude Desktop을 μ™„μ „νžˆ μ’…λ£Œν–ˆλ‹€κ°€ λ‹€μ‹œ μ‹€ν–‰ν•˜μ„Έμš”.

### Claude Code

```bash
claude mcp add kobis -e KOBIS_API_KEY=여기에_λ°œκΈ‰λ°›μ€_ν‚€ -- npx -y github:cocossi381-cell/kobis-mcp
```

### 직접 λ‚΄λ €λ°›μ•„ μ“°κΈ° (.env 방식)

```bash
git clone https://github.com/cocossi381-cell/kobis-mcp.git
cd kobis-mcp
npm install
cp .env.example .env      # .env νŒŒμΌμ„ μ—΄μ–΄ KOBIS_API_KEY= 뒀에 ν‚€ μž…λ ₯
```

이 경우 MCP 섀정은 λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€. κ²½λ‘œλŠ” 내렀받은 μœ„μΉ˜λ‘œ λ°”κΏ”μ£Όμ„Έμš”.

```json
{
  "mcpServers": {
    "kobis": {
      "command": "node",
      "args": ["/λ‚΄/폴더/경둜/kobis-mcp/index.js"]
    }
  }
}
```

> `.env` νŒŒμΌμ€ `.gitignore`에 ν¬ν•¨λ˜μ–΄ μžˆμ–΄ GitHub에 μ˜¬λΌκ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. ν‚€λŠ” μ ˆλŒ€ 곡개 μ €μž₯μ†Œμ— μ˜¬λ¦¬μ§€ λ§ˆμ„Έμš”.

---

## 3. 제곡 도ꡬ

| 도ꡬ | μ„€λͺ… | μ£Όμš” μž…λ ₯κ°’ |
|---|---|---|
| `get_daily_boxoffice` | 일별 λ°•μŠ€μ˜€ν”ΌμŠ€ (μ΅œλŒ€ 10μœ„) | `targetDt` (YYYYMMDD, μƒλž΅ μ‹œ μ–΄μ œ), `repNationCd` (K ν•œκ΅­ / F μ™Έκ΅­), `multiMovieYn` |
| `get_weekly_boxoffice` | 주간·주말·주쀑 λ°•μŠ€μ˜€ν”ΌμŠ€ | `targetDt`, `weekGb` (0 μ£Όκ°„ / 1 주말 / 2 주쀑) |
| `search_movies` | μ˜ν™” λͺ©λ‘ 검색 | `movieNm`, `directorNm`, `openStartDt`, `openEndDt` |
| `get_movie_info` | μ˜ν™” 상세정보 (감독, 배우, μž₯λ₯΄, λ“±κΈ‰, μƒμ˜μ‹œκ°„) | `movieCd` |
| `search_companies` | μ˜ν™”μ‚¬ 검색 | `companyNm`, `ceoNm` |
| `get_company_info` | μ˜ν™”μ‚¬ 상세정보 | `companyCd` |
| `search_people` | μ˜ν™”μΈ(λ°°μš°Β·κ°λ… λ“±) 검색 | `peopleNm`, `filmoNames` |
| `get_people_info` | μ˜ν™”μΈ 상세정보 (ν•„λͺ¨κ·Έλž˜ν”Ό) | `peopleCd` |
| `get_codes` | κ³΅ν†΅μ½”λ“œ 쑰회 | `comCode` (2201 μž₯λ₯΄, 2204 ꡭ적, 2601 μ˜ν™”μ‚¬ λΆ„λ₯˜ λ“±) |

μ°Έκ³ : λ°•μŠ€μ˜€ν”ΌμŠ€λŠ” **μ–΄μ œ λ‚ μ§œκΉŒμ§€λ§Œ** μ§‘κ³„λ©λ‹ˆλ‹€. 였늘 λ‚ μ§œλ‘œ μ‘°νšŒν•˜λ©΄ κ²°κ³Όκ°€ λΉ„μ–΄ μžˆμŠ΅λ‹ˆλ‹€.

---

## 4. 문제 ν•΄κ²°

| 증상 | ν•΄κ²° 방법 |
|---|---|
| `KOBIS_API_KEYκ°€ μ„€μ •λ˜μ§€ μ•Šμ•˜μŠ΅λ‹ˆλ‹€` | μ„€μ •μ˜ `env`에 ν‚€λ₯Ό λ„£μ—ˆλŠ”μ§€, λ˜λŠ” `.env` 파일이 μžˆλŠ”μ§€ ν™•μΈν•˜μ„Έμš”. |
| `μœ νš¨ν•˜μ§€μ•Šμ€ ν‚€κ°’μž…λ‹ˆλ‹€` | ν‚€λ₯Ό 잘λͺ» λ³΅μ‚¬ν–ˆκ±°λ‚˜ μ•žλ’€μ— 곡백이 듀어갔을 수 μžˆμŠ΅λ‹ˆλ‹€. |
| Claude에 도ꡬ가 μ•ˆ λ³΄μž„ | 앱을 μ™„μ „νžˆ μ’…λ£Œ ν›„ μž¬μ‹€ν–‰ν•˜μ„Έμš”. `node -v`둜 Node.js μ„€μΉ˜ 여뢀도 ν™•μΈν•˜μ„Έμš”. |
| 일일 호좜 μ œν•œ 초과 | KOBIS μ˜€ν”ˆAPIλŠ” ν‚€λ‹Ή ν•˜λ£¨ 호좜 횟수 μ œν•œμ΄ μžˆμŠ΅λ‹ˆλ‹€. λ‹€μŒ λ‚  λ‹€μ‹œ μ‹œλ„ν•˜μ„Έμš”. |

## 5. 직접 ν…ŒμŠ€νŠΈν•΄λ³΄κΈ° (개발자용)

```bash
KOBIS_API_KEY=λ°œκΈ‰λ°›μ€ν‚€ npx @modelcontextprotocol/inspector node index.js
```

λΈŒλΌμš°μ €μ— MCP Inspectorκ°€ 열리면 각 도ꡬλ₯Ό 직접 μ‹€ν–‰ν•΄ λ³Ό 수 μžˆμŠ΅λ‹ˆλ‹€.

---

## 데이터 좜처 및 λΌμ΄μ„ μŠ€

- 데이터: [μ˜ν™”μ§„ν₯μœ„μ›νšŒ KOBIS μ˜€ν”ˆAPI](https://www.kobis.or.kr/kobisopenapi). 데이터 이용 μ‹œ 좜처λ₯Ό ν‘œκΈ°ν•΄μ£Όμ„Έμš”.
- μ½”λ“œ: MIT License