KOBIS MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@KOBIS MCP Server 어제 일별 박스오피스 상위 5편 알려줘"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
KOBIS MCP Server
영화진흥위원회 영화관입장권통합전산망(KOBIS) Open API를 Claude, Codex, Cursor 같은 AI 클라이언트에서 쓸 수 있게 해 주는 읽기 전용 Model Context Protocol(MCP) 서버입니다. "어제 박스오피스 알려줘"처럼 말로 물어보면 AI가 KOBIS 데이터를 조회해서 답합니다.
이 저장소에는 API 키가 들어 있지 않습니다. 서버를 설치한 사람이 자기 KOBIS 키를.env 파일이나 MCP 클라이언트 설정에 직접 입력해서 사용합니다.
목차
Related MCP server: stock-market-mcp-server
제공 도구
도구 | 하는 일 |
| 일별 박스오피스 조회 |
| 주간·주말·주중 박스오피스 조회 |
| 영화 검색 (영화명, 감독명, 제작연도, 개봉일 등) |
| 영화 상세정보 조회 (감독, 배우, 장르, 관람 등급 등) |
| 영화인 검색 |
| 영화인 상세정보·필모그래피 조회 |
| 영화사 검색 |
| 영화사 상세정보 조회 |
모든 도구는 KOBIS 데이터를 읽기만 하며, 수정하거나 삭제하지 않습니다.
설치하기
1. 준비물
Node.js 20 이상: 터미널에서
node --version을 실행해v20이상인지 확인합니다.Git
KOBIS Open API 키: KOBIS Open API에 회원가입한 뒤 키 발급/관리 메뉴에서 발급받습니다. 발급받은 키는 GitHub, 메신저, 공개 문서에 올리지 마세요.
2. 내려받고 패키지 설치하기
git clone https://github.com/una4199/kobis-mcp-server.git
cd kobis-mcp-server
npm installZIP으로 내려받았다면 압축을 푼 폴더에서 npm install을 실행하면 됩니다.
3. 내 API 키 입력하기
예제 파일을 복사해 .env 파일을 만듭니다.
macOS/Linux:
cp .env.example .envWindows PowerShell:
Copy-Item .env.example .env.env 파일을 열어 예시 값을 내 키로 바꿉니다.
KOBIS_API_KEY=여기에_발급받은_API_키.env는 .gitignore에 들어 있어 Git에 올라가지 않습니다. .env 대신 MCP 클라이언트 설정에 키를 넣을 수도 있습니다. API 키 입력 방법을 참고하세요.
4. 빌드하고 확인하기
npm run build
npm test
npm run verify:mcp마지막 줄에 MCP verification passed: 8 tools discovered, missing-key guidance OK.가 보이면 준비가 끝난 것입니다. 이제 MCP 클라이언트에 연결합니다.
API 키 입력 방법
키는 아래 두 곳 중 한 곳에 넣으면 됩니다. 두 곳 모두에 있으면 MCP 클라이언트 설정이 우선합니다.
방법 | 넣는 곳 | 이럴 때 추천 |
A. | 프로젝트 폴더의 | 클라이언트 설정 파일에 키를 남기고 싶지 않을 때, 여러 클라이언트에서 같은 키를 쓸 때 |
B. 클라이언트 설정 | 각 클라이언트 MCP 설정의 |
|
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서버는 도구가 호출될 때 키를 이 순서로 찾습니다.
MCP 클라이언트가 넘겨준 환경 변수
KOBIS_API_KEY프로젝트 최상위 폴더의
.env파일 (클라이언트가 어느 폴더에서 서버를 실행해도 이 위치를 찾습니다)
키가 없거나 .env.example의 예시 값이 그대로 남아 있으면 서버는 꺼지지 않고, 도구를 호출했을 때 키를 넣는 방법을 알려 주는 메시지를 돌려줍니다.
MCP 클라이언트에 연결하기
어떤 클라이언트든 실행 명령은 같습니다.
명령어:
node인수:
/절대경로/kobis-mcp-server/dist/index.js
/절대경로/kobis-mcp-server는 내 컴퓨터의 실제 경로로 바꾸세요. 프로젝트 폴더에서 pwd(Windows는 cd)를 실행하면 확인할 수 있습니다. Windows의 JSON 설정에서는 경로의 \를 \\로 쓰거나 /로 바꿔 씁니다.
Claude Desktop
Claude 메뉴에서 Settings… → Developer → Edit Config를 누릅니다. 설정 파일 위치는 다음과 같습니다.
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
mcpServers에kobis를 추가합니다.{ "mcpServers": { "kobis": { "command": "node", "args": ["/절대경로/kobis-mcp-server/dist/index.js"] } } }.env대신 설정에 키를 직접 넣으려면env를 추가합니다.{ "mcpServers": { "kobis": { "command": "node", "args": ["/절대경로/kobis-mcp-server/dist/index.js"], "env": { "KOBIS_API_KEY": "여기에_발급받은_API_키" } } } }Claude Desktop을 완전히 종료했다가 다시 실행합니다.
Claude Code
# .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에 아래 내용을 넣습니다.
[mcp_servers.kobis]
command = "node"
args = ["/절대경로/kobis-mcp-server/dist/index.js"].env 대신 설정에 키를 넣으려면 다음 항목을 추가합니다.
[mcp_servers.kobis.env]
KOBIS_API_KEY = "여기에_발급받은_API_키"설정한 뒤 Codex를 다시 시작하고 /mcp 또는 codex mcp list로 연결 상태를 확인합니다. 자세한 내용은 Codex MCP 공식 문서를 참고하세요.
Cursor 등 다른 클라이언트
Cursor는 ~/.cursor/mcp.json(모든 프로젝트) 또는 프로젝트의 .cursor/mcp.json에 Claude Desktop과 같은 mcpServers 형식으로 추가합니다. 다른 MCP 클라이언트도 대부분 같은 형식을 쓰므로, 설정 파일 위치만 각 클라이언트 문서에서 확인하면 됩니다.
사용 예시와 결과
이렇게 물어보면 됩니다
질문 | AI가 호출하는 도구 | 받는 결과 |
어제 박스오피스 TOP 5 알려줘 |
| 순위, 영화명, 관객수, 전일 대비 증감, 누적 관객수 |
지난 주말 한국 영화 박스오피스만 보여줘 |
| 주말 기준 한국 영화 순위표 |
제목에 '기생충'이 들어간 영화 찾아줘 |
| 영화 코드, 제작연도, 개봉일, 장르, 감독 |
봉준호 감독의 필모그래피 보여줘 |
| 참여 작품과 역할 목록 |
「최종면접」의 감독과 출연진 알려줘 |
| 감독, 배우, 장르, 관람 등급 |
상세정보 도구에는 영화·영화인·영화사 코드가 필요합니다. AI가 먼저 검색 도구로 코드를 찾은 뒤 상세정보 도구를 이어서 호출합니다.
결과 예시: 일별 박스오피스
맨 위 예시 화면처럼, 도구는 KOBIS 응답(JSON)을 그대로 돌려주고 AI가 이를 읽기 좋게 정리해 답합니다. kobis_daily_box_office에 targetDt: "20261113"을 넣었을 때 받는 데이터는 다음과 같은 모양입니다. (2026년 11월 13일 기준, 일부 필드만 표시)
{
"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로 직접 확인하기
npx @modelcontextprotocol/inspector node dist/index.js브라우저가 열리면 Connect → Tools에서 도구를 골라 실행합니다. 예를 들어 kobis_daily_box_office의 targetDt에 20261113처럼 8자리 날짜를 넣습니다.
개발 명령어
npm run dev # TypeScript 소스를 바로 실행
npm run typecheck # 타입 오류 검사
npm test # 단위 테스트
npm run build # dist 폴더 빌드
npm run verify:mcp # 실제 MCP 연결, 도구 목록, 키 누락 안내 검증STDIO의 표준 출력은 MCP 통신 전용입니다. 서버 로그를 추가할 때는 console.log 대신 console.error를 사용하세요.
프로젝트 구조
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 클라이언트에서 서버가 보이지 않습니다
npm run build를 실행해dist/index.js가 만들어졌는지 확인합니다.설정의 경로가 절대경로인지 확인합니다.
node --version이 20 이상인지 확인합니다.nvm 등으로 Node.js를 설치했다면 클라이언트가
node를 찾지 못할 수 있습니다. 터미널에서which node(Windows는where node)로 나온 전체 경로를command에 넣습니다.클라이언트를 완전히 종료한 뒤 다시 실행합니다.
npm run verify:mcp로 서버 자체가 정상인지 확인합니다.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
API를 사용하는 사람은 KOBIS의 서비스 이용약관을 확인하고 지켜야 합니다.
이 서버의 소스 코드는 MIT License로 배포됩니다.
기여하기
버그 제보와 개선 제안은 GitHub Issues에 남겨 주세요. 변경을 제안하려면 저장소를 포크한 뒤 Pull Request를 보내면 됩니다.
Available Tools
8 toolskobis_company_detailsKOBIS 영화사 상세정보BRead-onlyIdempotent
KOBIS 영화사 코드로 상세정보와 관련 영화를 조회합니다.
Inputs: companyCd (required).
kobis_daily_box_officeKOBIS 일별 박스오피스BRead-onlyIdempotent
특정 날짜의 한국 영화관 일별 박스오피스 순위를 조회합니다.
Inputs: targetDt (required), wideAreaCd, itemPerPage, repNationCd, +1 more.
kobis_movie_detailsKOBIS 영화 상세정보BRead-onlyIdempotent
KOBIS 영화 코드로 영화의 상세정보를 조회합니다.
Inputs: movieCd (required).
kobis_person_detailsKOBIS 영화인 상세정보BRead-onlyIdempotent
KOBIS 영화인 코드로 상세정보와 필모그래피를 조회합니다.
Inputs: peopleCd (required).
kobis_search_companiesKOBIS 영화사 검색CRead-onlyIdempotent
영화사명이나 대표자명으로 영화사를 검색합니다.
Inputs: ceoNm, curPage, companyNm, itemPerPage.
kobis_search_moviesKOBIS 영화 검색CRead-onlyIdempotent
영화명, 감독명, 제작연도, 개봉일 등의 조건으로 영화를 검색합니다.
Inputs: curPage, movieNm, openEndDt, directorNm, +6 more.
kobis_search_peopleKOBIS 영화인 검색BRead-onlyIdempotent
영화인 이름이나 참여 영화명으로 영화인을 검색합니다.
Inputs: curPage, peopleNm, filmoNames, itemPerPage.
kobis_weekly_box_officeKOBIS 주간/주말 박스오피스BRead-onlyIdempotent
특정 날짜가 포함된 주의 주간·주말·주중 박스오피스 순위를 조회합니다.
Inputs: targetDt (required), weekGb, wideAreaCd, itemPerPage, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Film/TV public-record rights intelligence for AI agents with provenance and bounded verification.
Film/TV public-record rights intelligence for AI agents with provenance and bounded verification.
FlickDirect Inc’s free, read-only movie MCP server. Live service 1.5.11 provides movie and TV facts, cast, available country-specific dates and ratings, production trivia, brief quote excerpts, site-wide news and reviews, CinemaCon reporting, interviews and eligible stored transcripts. Cinema United association and year-round exhibition reporting use articles; CinemaCon remains its separate annual convention. FlickDirect’s independent guide is https://flickdirect.com/cinema-united/; the official association site is https://cinemaunited.org/. Find published podcast shows and episodes, including bounded FlickRadio archive matching. Recent uploads from three verified FlickDirect channels retain healthy-feed results when another feed times out, with incomplete coverage explicitly reported. Streaming, soundtrack/player and published Amazon and Apple destinations remain supported. Retailer listings and daily deals are no longer supported. Longer-title recovery preserves original title words and requested year/media filters. The tools are search_flickdirect_content and get_flickdirect_movie_details. Cached search_fdmd and get_fdmd_movie calls remain compatible at the unchanged endpoint. Results retain canonical source links and distinguish missing matches, unavailable sources and ambiguity. Fetch time does not prove upstream currentness. No full articles, reviews, transcripts, scripts or photographs. Playback and tool selection depend on the AI host. Private request diagnostics expire within seven days. No FlickDirect account or API key is required.
Rights-aware documentary search, film details, and where-to-watch for AI assistants. 100,000+ films.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables AI assistants to access and analyze financial data including stock information, company fundamentals, and market insights through the Financial Modeling Prep API.267558 npm149TypeScriptApache 2.0
- AlicenseNot gradedqualityFmaintenanceEnables LLMs to access stock market and cryptocurrency data through the Financial Datasets API, including financial statements, prices, metrics, and press releases.17 npmMIT

ROIC.ai Financial Data MCPofficial
AlicenseAqualityCmaintenanceEnables AI assistants to access stock prices, financial statements, earnings call transcripts, and fundamental data for 60,000+ public companies via 25 read-only tools.2528 npm4MIT- AlicenseNot gradedqualityBmaintenanceEnables AI agents to retrieve real-time market quotes, company financials, earnings calendars, news with sentiment, insider transactions, ETF holdings, and international ticker data via a market-data REST API.142 npmMIT