Skip to main content
Glama
KOBIS MCP Server

KOBIS MCP Server

by una4199
README.md
# KOBIS MCP Server

[![CI](https://github.com/una4199/kobis-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/una4199/kobis-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)

[영화진흥위원회 영화관입장권통합전산망(KOBIS) Open API](https://www.kobis.or.kr/kobisopenapi/homepg/main/main.do)를 Claude, Codex, Cursor 같은 AI 클라이언트에서 쓸 수 있게 해 주는 읽기 전용 [Model Context Protocol(MCP)](https://modelcontextprotocol.io/) 서버입니다. "어제 박스오피스 알려줘"처럼 말로 물어보면 AI가 KOBIS 데이터를 조회해서 답합니다.

<p align="center">
  <img src="docs/images/example-daily-box-office.png" width="760" alt="MCP 클라이언트에서 '어제 박스오피스 TOP 5 알려줘'라고 묻자 kobis_daily_box_office 도구가 호출되고, AI가 순위·관객수·누적 관객수를 표로 정리해 답하는 예시 화면">
</p>
<p align="center"><sub>예시 화면 (2026년 11월 13일 KOBIS 집계 기준). 실제 화면은 사용하는 MCP 클라이언트에 따라 다릅니다.</sub></p>

> [!IMPORTANT]
> 이 저장소에는 API 키가 들어 있지 않습니다. 서버를 설치한 사람이 자기 KOBIS 키를 `.env` 파일이나 MCP 클라이언트 설정에 직접 입력해서 사용합니다.

## 목차

- [제공 도구](#제공-도구)
- [설치하기](#설치하기)
- [API 키 입력 방법](#api-키-입력-방법)
- [MCP 클라이언트에 연결하기](#mcp-클라이언트에-연결하기)
- [사용 예시와 결과](#사용-예시와-결과)
- [동작 확인과 개발](#동작-확인과-개발)
- [문제 해결](#문제-해결)
- [보안](#보안)

## 제공 도구

| 도구 | 하는 일 |
|---|---|
| `kobis_daily_box_office` | 일별 박스오피스 조회 |
| `kobis_weekly_box_office` | 주간·주말·주중 박스오피스 조회 |
| `kobis_search_movies` | 영화 검색 (영화명, 감독명, 제작연도, 개봉일 등) |
| `kobis_movie_details` | 영화 상세정보 조회 (감독, 배우, 장르, 관람 등급 등) |
| `kobis_search_people` | 영화인 검색 |
| `kobis_person_details` | 영화인 상세정보·필모그래피 조회 |
| `kobis_search_companies` | 영화사 검색 |
| `kobis_company_details` | 영화사 상세정보 조회 |

모든 도구는 KOBIS 데이터를 읽기만 하며, 수정하거나 삭제하지 않습니다.

## 설치하기

### 1. 준비물

- **Node.js 20 이상**: 터미널에서 `node --version`을 실행해 `v20` 이상인지 확인합니다.
- **Git**
- **KOBIS Open API 키**: [KOBIS Open API](https://www.kobis.or.kr/kobisopenapi/homepg/main/main.do)에 회원가입한 뒤 **키 발급/관리** 메뉴에서 발급받습니다. 발급받은 키는 GitHub, 메신저, 공개 문서에 올리지 마세요.

### 2. 내려받고 패키지 설치하기

```bash
git clone https://github.com/una4199/kobis-mcp-server.git
cd kobis-mcp-server
npm install
```

ZIP으로 내려받았다면 압축을 푼 폴더에서 `npm install`을 실행하면 됩니다.

### 3. 내 API 키 입력하기

예제 파일을 복사해 `.env` 파일을 만듭니다.

macOS/Linux:

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

Windows PowerShell:

```powershell
Copy-Item .env.example .env
```

`.env` 파일을 열어 예시 값을 내 키로 바꿉니다.

```dotenv
KOBIS_API_KEY=여기에_발급받은_API_키
```

`.env`는 `.gitignore`에 들어 있어 Git에 올라가지 않습니다. `.env` 대신 MCP 클라이언트 설정에 키를 넣을 수도 있습니다. [API 키 입력 방법](#api-키-입력-방법)을 참고하세요.

### 4. 빌드하고 확인하기

```bash
npm run build
npm test
npm run verify:mcp
```

마지막 줄에 `MCP verification passed: 8 tools discovered, missing-key guidance OK.`가 보이면 준비가 끝난 것입니다. 이제 [MCP 클라이언트에 연결](#mcp-클라이언트에-연결하기)합니다.

## API 키 입력 방법

키는 아래 두 곳 중 한 곳에 넣으면 됩니다. 두 곳 모두에 있으면 **MCP 클라이언트 설정이 우선**합니다.

| 방법 | 넣는 곳 | 이럴 때 추천 |
|---|---|---|
| A. `.env` 파일 (권장) | 프로젝트 폴더의 `.env` | 클라이언트 설정 파일에 키를 남기고 싶지 않을 때, 여러 클라이언트에서 같은 키를 쓸 때 |
| B. 클라이언트 설정 | 각 클라이언트 MCP 설정의 `env` | `.env` 파일을 만들기 어렵거나, 클라이언트마다 다른 키를 쓰고 싶을 때 |

```mermaid
flowchart LR
    subgraph repo["GitHub 저장소 (공개)"]
        example[".env.example<br/>형식만 있고 키는 없음"]
    end
    subgraph pc["내 컴퓨터"]
        dotenv[".env<br/>KOBIS_API_KEY=내 키"]
        client["MCP 클라이언트 설정<br/>env.KOBIS_API_KEY"]
        server["kobis-mcp-server"]
    end
    kobis[("KOBIS Open API")]

    example -- "복사한 뒤 키 입력" --> dotenv
    client -- "1순위" --> server
    dotenv -- "2순위" --> server
    server -- "HTTPS 요청" --> kobis
```

서버는 도구가 호출될 때 키를 이 순서로 찾습니다.

1. MCP 클라이언트가 넘겨준 환경 변수 `KOBIS_API_KEY`
2. 프로젝트 최상위 폴더의 `.env` 파일 (클라이언트가 어느 폴더에서 서버를 실행해도 이 위치를 찾습니다)

키가 없거나 `.env.example`의 예시 값이 그대로 남아 있으면 서버는 꺼지지 않고, 도구를 호출했을 때 키를 넣는 방법을 알려 주는 메시지를 돌려줍니다.

## MCP 클라이언트에 연결하기

어떤 클라이언트든 실행 명령은 같습니다.

- 명령어: `node`
- 인수: `/절대경로/kobis-mcp-server/dist/index.js`

`/절대경로/kobis-mcp-server`는 내 컴퓨터의 실제 경로로 바꾸세요. 프로젝트 폴더에서 `pwd`(Windows는 `cd`)를 실행하면 확인할 수 있습니다. Windows의 JSON 설정에서는 경로의 `\`를 `\\`로 쓰거나 `/`로 바꿔 씁니다.

### Claude Desktop

1. Claude 메뉴에서 **Settings…** → **Developer** → **Edit Config**를 누릅니다. 설정 파일 위치는 다음과 같습니다.
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. `mcpServers`에 `kobis`를 추가합니다.

   ```json
   {
     "mcpServers": {
       "kobis": {
         "command": "node",
         "args": ["/절대경로/kobis-mcp-server/dist/index.js"]
       }
     }
   }
   ```

   `.env` 대신 설정에 키를 직접 넣으려면 `env`를 추가합니다.

   ```json
   {
     "mcpServers": {
       "kobis": {
         "command": "node",
         "args": ["/절대경로/kobis-mcp-server/dist/index.js"],
         "env": {
           "KOBIS_API_KEY": "여기에_발급받은_API_키"
         }
       }
     }
   }
   ```

3. Claude Desktop을 완전히 종료했다가 다시 실행합니다.

### Claude Code

```bash
# .env에 키를 넣은 경우
claude mcp add --transport stdio kobis -- node /절대경로/kobis-mcp-server/dist/index.js

# 키를 설정에 직접 넣는 경우
claude mcp add --env KOBIS_API_KEY=여기에_발급받은_API_키 --transport stdio kobis -- node /절대경로/kobis-mcp-server/dist/index.js
```

모든 프로젝트에서 쓰려면 `--scope user`를 추가합니다. 연결 상태는 `claude mcp list` 또는 Claude Code 안에서 `/mcp`로 확인합니다. `--scope project`로 추가하면 설정이 저장소의 `.mcp.json`에 저장되므로, 이때는 키를 직접 넣지 말고 `.env`를 사용하세요.

### Codex

Codex 데스크톱 앱에서는 **Settings → MCP servers → Add server**에서 STDIO 서버를 추가합니다.

- 이름: `kobis`
- 종류: `STDIO`
- 명령어: `node`
- 인수: `/절대경로/kobis-mcp-server/dist/index.js`

설정 파일로 추가하려면 `~/.codex/config.toml`에 아래 내용을 넣습니다.

```toml
[mcp_servers.kobis]
command = "node"
args = ["/절대경로/kobis-mcp-server/dist/index.js"]
```

`.env` 대신 설정에 키를 넣으려면 다음 항목을 추가합니다.

```toml
[mcp_servers.kobis.env]
KOBIS_API_KEY = "여기에_발급받은_API_키"
```

설정한 뒤 Codex를 다시 시작하고 `/mcp` 또는 `codex mcp list`로 연결 상태를 확인합니다. 자세한 내용은 [Codex MCP 공식 문서](https://developers.openai.com/codex/extend/mcp)를 참고하세요.

### Cursor 등 다른 클라이언트

Cursor는 `~/.cursor/mcp.json`(모든 프로젝트) 또는 프로젝트의 `.cursor/mcp.json`에 Claude Desktop과 같은 `mcpServers` 형식으로 추가합니다. 다른 MCP 클라이언트도 대부분 같은 형식을 쓰므로, 설정 파일 위치만 각 클라이언트 문서에서 확인하면 됩니다.

## 사용 예시와 결과

### 이렇게 물어보면 됩니다

| 질문 | AI가 호출하는 도구 | 받는 결과 |
|---|---|---|
| 어제 박스오피스 TOP 5 알려줘 | `kobis_daily_box_office` | 순위, 영화명, 관객수, 전일 대비 증감, 누적 관객수 |
| 지난 주말 한국 영화 박스오피스만 보여줘 | `kobis_weekly_box_office` | 주말 기준 한국 영화 순위표 |
| 제목에 '기생충'이 들어간 영화 찾아줘 | `kobis_search_movies` | 영화 코드, 제작연도, 개봉일, 장르, 감독 |
| 봉준호 감독의 필모그래피 보여줘 | `kobis_search_people` → `kobis_person_details` | 참여 작품과 역할 목록 |
| 「최종면접」의 감독과 출연진 알려줘 | `kobis_search_movies` → `kobis_movie_details` | 감독, 배우, 장르, 관람 등급 |

상세정보 도구에는 영화·영화인·영화사 코드가 필요합니다. AI가 먼저 검색 도구로 코드를 찾은 뒤 상세정보 도구를 이어서 호출합니다.

### 결과 예시: 일별 박스오피스

맨 위 예시 화면처럼, 도구는 KOBIS 응답(JSON)을 그대로 돌려주고 AI가 이를 읽기 좋게 정리해 답합니다. `kobis_daily_box_office`에 `targetDt: "20261113"`을 넣었을 때 받는 데이터는 다음과 같은 모양입니다. (2026년 11월 13일 기준, 일부 필드만 표시)

```jsonc
{
  "boxOfficeResult": {
    "boxofficeType": "일별 박스오피스",
    "showRange": "20261113~20261113",
    "dailyBoxOfficeList": [
      {
        "rank": "1",                 // 순위
        "rankInten": "0",            // 전일 대비 순위 변동
        "movieNm": "폴2: 데드포인트",   // 영화명
        "openDt": "2026-11-11",      // 개봉일
        "audiCnt": "19162",          // 해당일 관객수
        "audiInten": "6790",         // 전일 대비 관객수 증감
        "audiAcc": "51667",          // 누적 관객수
        "scrnCnt": "749"             // 상영 스크린 수
        // movieCd, salesAmt, salesShare, showCnt 등은 생략
      }
      // 2위 이하 생략
    ]
  }
}
```

## 동작 확인과 개발

### MCP Inspector로 직접 확인하기

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

브라우저가 열리면 **Connect → Tools**에서 도구를 골라 실행합니다. 예를 들어 `kobis_daily_box_office`의 `targetDt`에 `20261113`처럼 8자리 날짜를 넣습니다.

### 개발 명령어

```bash
npm run dev         # TypeScript 소스를 바로 실행
npm run typecheck   # 타입 오류 검사
npm test            # 단위 테스트
npm run build       # dist 폴더 빌드
npm run verify:mcp  # 실제 MCP 연결, 도구 목록, 키 누락 안내 검증
```

STDIO의 표준 출력은 MCP 통신 전용입니다. 서버 로그를 추가할 때는 `console.log` 대신 `console.error`를 사용하세요.

### 프로젝트 구조

```text
kobis-mcp-server/
├── src/
│   ├── index.ts          # MCP 서버와 도구 8개 정의
│   ├── config.ts         # API 키 읽기 (클라이언트 환경 변수 → .env)
│   └── kobis-client.ts   # KOBIS API 호출, 오류 처리, 키 가리기
├── test/                 # 단위 테스트
├── scripts/
│   └── verify-mcp.ts     # MCP 연결 검증 스크립트
├── docs/images/          # README 이미지
├── .env.example          # API 키 입력 형식 (실제 키 없음)
└── .github/workflows/
    └── ci.yml            # 푸시할 때마다 테스트·빌드·MCP 검증
```

## 문제 해결

### `KOBIS_API_KEY가 없습니다`

`.env` 파일이 프로젝트 최상위 폴더(`package.json`이 있는 곳)에 있는지, 변수명이 정확히 `KOBIS_API_KEY`인지 확인합니다. Windows 메모장으로 만들었다면 파일 이름이 `.env.txt`로 저장되지 않았는지도 확인하세요.

### `KOBIS_API_KEY가 예시 값 그대로입니다`

`.env`나 클라이언트 설정의 값을 KOBIS에서 발급받은 실제 키로 바꿉니다.

### KOBIS가 키가 올바르지 않다는 오류를 돌려줍니다

발급받은 키를 빠짐없이 정확히 복사했는지 확인하고, KOBIS **키 발급/관리** 페이지에서 키 상태를 확인합니다.

### `KOBIS API 연결에 실패했습니다`

인터넷 연결을 확인하고, 회사나 학교 네트워크의 방화벽·프록시가 `www.kobis.or.kr` 접속을 막고 있지 않은지 확인합니다.

### MCP 클라이언트에서 서버가 보이지 않습니다

1. `npm run build`를 실행해 `dist/index.js`가 만들어졌는지 확인합니다.
2. 설정의 경로가 절대경로인지 확인합니다.
3. `node --version`이 20 이상인지 확인합니다.
4. nvm 등으로 Node.js를 설치했다면 클라이언트가 `node`를 찾지 못할 수 있습니다. 터미널에서 `which node`(Windows는 `where node`)로 나온 전체 경로를 `command`에 넣습니다.
5. 클라이언트를 완전히 종료한 뒤 다시 실행합니다.
6. `npm run verify:mcp`로 서버 자체가 정상인지 확인합니다.
7. Claude Desktop이라면 로그를 확인합니다. macOS는 `~/Library/Logs/Claude/mcp-server-kobis.log`, Windows는 `%APPDATA%\Claude\logs\mcp-server-kobis.log`입니다.

## 보안

- API 키는 소스 코드, README, 커밋에 넣지 않습니다. 저장소에는 형식만 담긴 `.env.example`만 있습니다.
- `.env`와 `.env.*` 파일은 `.gitignore`로 제외됩니다. (`.env.example`만 예외)
- 오류 메시지에 키가 섞여 들어가면 `***`로 가린 뒤 클라이언트에 돌려줍니다.
- 저장소에 함께 올라가는 설정 파일(`.mcp.json`, `.cursor/mcp.json` 등)에는 키를 직접 쓰지 말고 `.env`를 사용합니다.
- 키가 공개되었다면 KOBIS에서 해당 키를 폐기하고 새로 발급받습니다.

## 데이터 및 라이선스

- 데이터 제공: [영화진흥위원회 KOBIS Open API](https://www.kobis.or.kr/kobisopenapi/homepg/apiservice/searchServiceInfo.do)
- API를 사용하는 사람은 KOBIS의 [서비스 이용약관](https://www.kobis.or.kr/kobisopenapi/homepg/board/findServiceGuideList.do?menuId=09)을 확인하고 지켜야 합니다.
- 이 서버의 소스 코드는 [MIT License](LICENSE)로 배포됩니다.

## 기여하기

버그 제보와 개선 제안은 [GitHub Issues](https://github.com/una4199/kobis-mcp-server/issues)에 남겨 주세요. 변경을 제안하려면 저장소를 포크한 뒤 Pull Request를 보내면 됩니다.

TDQS

A3.5/5.0

Scored across 8 tools

Disambiguation4/5

Each tool maps to a distinct resource and action: box office (daily vs weekly), movie search vs details, people search vs details, company search vs details. The only mild overlap is between the two box office tools, but their descriptions clearly differentiate a single date from a week range.

Naming Consistency4/5

All names share a consistent kobis_ prefix and snake_case convention. There is a minor structural deviation between verb-first search tools (kobis_search_movies) and noun-first detail tools (kobis_movie_details), but the pattern remains highly readable.

Tool Count5/5

Eight tools is a well-scoped set that mirrors the natural structure of the KOBIS domain without redundancy. Each tool earns its place, pairing one search and one detail lookup per entity plus two box office views.

Completeness4/5

The surface covers box office rankings, movie search/details, people search/details, and company search/details, which spans the core KOBIS API workflows. Minor gaps remain, such as monthly or genre box office and bulk list endpoints, but agents can work around these via date-based and search queries.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues