# TMDB 영화 API MCP 서버  
이 프로젝트는 TMDB(The Movie Database) API를 Model Context Protocol(MCP) 서버로 제공합니다. MCP는 LLM(Large Language Model) 애플리케이션이 다양한 데이터 소스와 도구를 통합할 수 있는 표준 프로토콜입니다.
## 기능
- 영화 제목/키워드로 영화 검색
- 영화 상세 정보 조회 (줄거리, 평점, 장르, 제작사 등)
- 영화 출연진 및 제작진 정보 조회
- 현재 상영 중인 영화 목록
- 개봉 예정 영화 목록
- 인기 영화 순위
- 평점 높은 영화 목록
- 배우, 감독 등 인물 검색
- TV 프로그램 검색 (기본 기능)
## 설치
### 글로벌 설치
```bash
npm install -g tmdb-mcp-server
```
### 프로젝트에 설치
```bash
npm install tmdb-mcp-server
```
### 소스에서 설치
```bash
git clone https://github.com/your-repo/tmdb-mcp-server.git
cd tmdb-mcp-server
npm install
npm run build
```
## 설정
다음 두 가지 방법 중 하나로 TMDB API 키를 설정할 수 있습니다:
### 1. 설정 파일 사용
`config/config.json` 파일을 생성하고 TMDB API 키를 설정합니다:
```json
{
"tmdbApiKey": "your_tmdb_api_key_here"
}
```
또는 다음 위치에 config.json 파일을 생성할 수 있습니다:
- `~/.config/tmdbMCP/config.json` (사용자 홈 디렉토리)
- 현재 작업 디렉토리의 `config.json`
### 2. 환경 변수 사용
`TMDB_API_KEY` 환경 변수에 API 키를 설정할 수 있습니다:
```bash
export TMDB_API_KEY=your_tmdb_api_key_here
```
TMDB API 키는 [TMDB 웹사이트](https://www.themoviedb.org/settings/api)에서 무료로 발급받을 수 있습니다.
## 실행
### 글로벌 설치 후 실행
```bash
tmdb-mcp-server
```
### 소스에서 실행
```bash
npm run build
npm start
```
## 개발
개발 모드로 실행하려면:
```bash
npm run dev
```
## Usage
### Claude Desktop과 함께 사용하기
Claude Desktop 앱에서 이 MCP 서버를 사용하는 가장 안정적인 방법은 로컬에서 소스 코드를 실행하는 것입니다:
```json
{
"mcpServers": {
"tmdb": {
"command": "node",
"args": [
"/절대/경로/tmdb-mcp-server/dist/index.js"
],
"env": {
"TMDB_API_KEY": "your_tmdb_api_key_here"
}
}
}
}
```
주의사항:
- `/절대/경로/tmdb-mcp-server/dist/index.js`를 서버 파일의 실제 절대 경로로 변경하세요.
- Windows에서는 경로를 `C:\\경로\\tmdb-mcp-server\\dist\\index.js` 형식으로 사용하세요.
- 환경 변수 대신 config.json 파일을 사용할 경우, 해당 파일이 이 README의 [설정](#설정) 섹션에 나열된 위치 중 하나에 생성되어 있는지 확인하세요.
**참고**: 다음 방법들도 시도해볼 수 있으나, 환경에 따라 작동하지 않을 수 있습니다.
1. 패키지를 전역으로 설치한 후 직접 실행:
```bash
npm install -g tmdb-mcp-server
```
```json
{
"mcpServers": {
"tmdb": {
"command": "tmdb-mcp-server",
"env": {
"TMDB_API_KEY": "your_tmdb_api_key_here"
}
}
}
}
```
2. Node require 방식:
```json
{
"mcpServers": {
"tmdb": {
"command": "node",
"args": [
"-e",
"require('tmdb-mcp-server')"
],
"env": {
"TMDB_API_KEY": "your_tmdb_api_key_here"
}
}
}
}
```
## MCP 도구
### 영화 검색 및 정보 조회
- `search-movies` - 영화 검색
- 매개변수:
- `query`: 검색어 (영화 제목, 키워드)
- `page`: 페이지 번호 (기본값: 1)
- `get-movie-details` - 영화 상세 정보 조회
- 매개변수:
- `movieId`: TMDB 영화 ID
- `get-movie-credits` - 영화 출연진 및 제작진 정보
- 매개변수:
- `movieId`: TMDB 영화 ID
### 영화 목록 조회
- `get-now-playing-movies` - 현재 상영 중인 영화 목록
- 매개변수:
- `page`: 페이지 번호 (기본값: 1)
- `get-upcoming-movies` - 개봉 예정 영화 목록
- 매개변수:
- `page`: 페이지 번호 (기본값: 1)
- `get-popular-movies` - 인기 영화 목록
- 매개변수:
- `page`: 페이지 번호 (기본값: 1)
- `get-top-rated-movies` - 평점 높은 영화 목록
- 매개변수:
- `page`: 페이지 번호 (기본값: 1)
### 인물 검색
- `search-person` - 배우, 감독 등 인물 검색
- 매개변수:
- `query`: 검색어 (인물 이름)
- `page`: 페이지 번호 (기본값: 1)
## 사용 예시
### 영화 검색
```
사용자: "어벤져스 영화를 찾아줘"
AI: search-movies 도구를 사용하여 "어벤져스" 관련 영화를 검색하고 결과를 표시합니다.
```
### 영화 상세 정보
```
사용자: "영화 ID 299536의 상세 정보를 알려줘"
AI: get-movie-details 도구를 사용하여 해당 영화의 상세 정보를 제공합니다.
```
### 현재 상영작 확인
```
사용자: "지금 극장에서 상영 중인 영화 목록을 보여줘"
AI: get-now-playing-movies 도구를 사용하여 현재 상영 중인 영화 목록을 제공합니다.
```
### 인기 영화 순위
```
사용자: "요즘 인기 있는 영화 순위를 알려줘"
AI: get-popular-movies 도구를 사용하여 인기 영화 목록을 제공합니다.
```
### 배우 검색
```
사용자: "톰 행크스가 나온 영화를 찾아줘"
AI: search-person 도구로 톰 행크스를 검색하고 관련 영화 정보를 제공합니다.
```
## API 제한 사항
- TMDB API는 일일 요청 제한이 있습니다 (무료 계정: 1,000 요청/일)
- 과도한 요청을 방지하기 위해 적절한 지연 시간을 두는 것이 좋습니다
- 상용 사용 시 TMDB의 이용 약관을 확인하세요
## 기여
버그 리포트나 기능 제안은 GitHub Issues를 통해 제출해주세요.
## 라이센스
이 프로젝트는 ISC 라이센스 하에 배포됩니다.
## 지원
문제가 있거나 도움이 필요한 경우:
1. 이 README의 설정 섹션을 다시 확인하세요
2. TMDB API 키가 올바르게 설정되었는지 확인하세요
3. GitHub Issues에 문제를 보고하세요
---
**참고**: 이 서버는 TMDB API를 사용하며, TMDB의 이용 약관을 준수합니다. 영화 데이터의 저작권은 해당 권리자에게 있습니다.
