TMDB 영화 API MCP 서버

이 프로젝트는 TMDB(The Movie Database) API를 Model Context Protocol(MCP) 서버로 제공합니다. MCP는 LLM(Large Language Model) 애플리케이션이 다양한 데이터 소스와 도구를 통합할 수 있는 표준 프로토콜입니다.

기능

• 영화 제목/키워드로 영화 검색
• 영화 상세 정보 조회 (줄거리, 평점, 장르, 제작사 등)
• 영화 출연진 및 제작진 정보 조회
• 현재 상영 중인 영화 목록
• 개봉 예정 영화 목록
• 인기 영화 순위
• 평점 높은 영화 목록
• 배우, 감독 등 인물 검색
• TV 프로그램 검색 (기본 기능)

설치

글로벌 설치

npm install -g tmdb-mcp-server

프로젝트에 설치

npm install tmdb-mcp-server

소스에서 설치

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 키를 설정합니다:

{
  "tmdbApiKey": "your_tmdb_api_key_here"
}

또는 다음 위치에 config.json 파일을 생성할 수 있습니다:

• ~/.config/tmdbMCP/config.json (사용자 홈 디렉토리)
• 현재 작업 디렉토리의 config.json

2. 환경 변수 사용

TMDB_API_KEY 환경 변수에 API 키를 설정할 수 있습니다:

export TMDB_API_KEY=your_tmdb_api_key_here

TMDB API 키는 TMDB 웹사이트에서 무료로 발급받을 수 있습니다.

실행

글로벌 설치 후 실행

tmdb-mcp-server

소스에서 실행

npm run build
npm start

개발

개발 모드로 실행하려면:

npm run dev

Usage

Claude Desktop과 함께 사용하기

Claude Desktop 앱에서 이 MCP 서버를 사용하는 가장 안정적인 방법은 로컬에서 소스 코드를 실행하는 것입니다:

{
  "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. 패키지를 전역으로 설치한 후 직접 실행:

npm install -g tmdb-mcp-server

{
  "mcpServers": {
    "tmdb": {
      "command": "tmdb-mcp-server",
      "env": {
        "TMDB_API_KEY": "your_tmdb_api_key_here"
      }
    }
  }
}

2. Node require 방식:

{
  "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의 이용 약관을 준수합니다. 영화 데이터의 저작권은 해당 권리자에게 있습니다.