TMDB MCP 서버

The Movie Database (TMDB) API를 위한 MCP 서버입니다. Codex 및 Claude Desktop과 같은 어시스턴트를 위해 영화 및 TV 검색, 스트리밍 가용성, 출연진 및 제작진 정보, 추천 기능을 제공합니다.

도구

영화 탐색

• get_weekend_watchlist — 분위기, 국가, 언어, 상영 시간, 평점, 서비스별로 순위가 매겨진 주말 추천 목록

• search_movies — 제목/키워드로 검색 → 제목, ID, 평점, 개요

• get_trending — 상위 10개 인기 영화 (timeWindow: "day" | "week")

• get_weekly_trending_by_language — 원어별(영어, 힌디어, 텔루구어)로 그룹화된 주간 인기 영화

• search_by_genre — 장르 이름별 영화, 선택적 연도 필터

• advanced_search — 장르, 연도, 최소 평점, 정렬, 언어별 필터링

• search_by_keyword — 테마/키워드로 영화 찾기 (예: "zombie", "heist")

영화 상세 정보

• get_movie_details — 전체 상세 정보: 출연진, 제작진, 상영 시간, 장르, 리뷰 (movieId 기준)

• compare_movies — 2~5개의 영화 ID를 평점, 상영 시간, 출연진, 감독, 제공업체 및 적합성 메모와 함께 나란히 비교

• get_recommendations — 영화 ID를 기반으로 상위 5개 추천

• get_similar_movies — TMDB의 유사성 알고리즘을 통한 유사 영화

• get_watch_providers — 국가별 스트리밍/대여/구매 가용성 (기본값: IN)

• find_where_to_watch — 1~5개의 영화 제목을 검색하여 선호 서비스와 일치하는 스트리밍/대여/구매 가용성 반환

TV 쇼

• search_tv_shows — 제목으로 TV 시리즈 검색

• get_trending_tv — 상위 10개 인기 TV 쇼 (timeWindow: "day" | "week")

인물

• search_person — 이름으로 배우, 감독, 제작진 찾기 → ID + 알려진 작품

• get_person_details — personId별 전체 약력 + 필모그래피 (영화 + TV)

리소스

• tmdb:///movie/<id> — JSON 형식의 전체 영화 상세 정보 (제목, 출연진, 감독, 리뷰, 포스터 URL)

Related MCP server: Usher MCP

빠른 시작

1. themoviedb.org에서 TMDB API 키를 받으세요 → 계정 설정 → API

2. 복제, 설치 및 빌드:

   git clone https://github.com/Laksh-star/mcp-server-tmdb.git
   cd mcp-server-tmdb
   npm install

3. 로컬 env 파일을 만들고 TMDB 키를 추가하세요:

   cp .env.example .env

4. 로컬 Codex 및 Claude Desktop 통합을 설치하세요:

   npm run install:local

5. 이미 열려 있는 경우 Codex 또는 Claude Desktop을 다시 시작하세요.

6. 다음과 같은 프롬프트로 확인하세요:

   What movies are trending this week?

Codex에서 새로운 세션을 시작하면 플러그인 목록에 TMDB가 표시되고 mcp__tmdb__ 네임스페이스가 노출되어야 합니다.

도구 표면 스모크 테스트

도구를 추가하거나 병합한 후 이 스모크 테스트를 사용하세요. 예상되는 MCP 도구 계약을 확인하고 주요 워크플로우 도구인 compare_movies, find_where_to_watch, get_weekend_watchlist를 호출합니다.

로컬 stdio MCP:

npm run build
set -a && source ./.env && set +a && npm run smoke:tools

Cloudflare 호스팅 MCP:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/tool-surface-smoke.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

스크립트는 다음 위치에 간결한 검증 아티팩트를 작성합니다:

examples/tool-surface-smoke.md

도구 비대화를 방지하려면 여러 TMDB 호출을 유용한 사용자 결정으로 결합하는 워크플로우 도구를 추가하는 것을 선호합니다. 원시 엔드포인트 스타일 도구는 광범위하게 재사용 가능한 기본 요소인 경우에만 유지하세요.

주간 인기 언어 데모

이 저장소에는 MCP 도구 get_weekly_trending_by_language를 호출하는 작은 공유 가능한 데모가 포함되어 있습니다. 이 도구는 실시간 TMDB 주간 인기 영화를 가져와 현재 첫 페이지를 TMDB original_language별로 그룹화합니다.

로컬 stdio MCP 서버에 대해 실행하세요:

npm run build
set -a && source ./.env && set +a && npm run demo:weekly-trending

이 버전의 Worker를 배포한 후 원격 MCP 엔드포인트에 대해 동일한 데모를 실행하세요:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-trending-languages.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

개인 테스트를 위해 인증 없이 배포하는 경우 TMDB_MCP_ACCESS_TOKEN을 생략하세요.

Cloudflare Workers의 원격 MCP

이 저장소는 Cloudflare Workers에서 원격 MCP 서버로 실행될 수도 있습니다. 원격 서버는 Streamable HTTP를 통해 /mcp에서 동일한 TMDB 도구를 노출하므로 Claude, Cowork, Claude Desktop 커넥터 및 기타 원격 MCP 클라이언트가 공용 URL에 연결할 수 있습니다.

기존 로컬 stdio 서버는 Codex 및 로컬 Claude Desktop 사용을 위해 변경되지 않은 상태로 유지됩니다. Cloudflare 진입점은 src/worker.ts입니다.

Worker는 /에서 브라우저 데모인 **주말 시청 컨시어지(Weekend Watch Concierge)**도 제공합니다. 분위기, 국가, 언어, 상영 시간, 평점 및 스트리밍 서비스를 요청한 다음 TMDB 탐색, 인기 영화, 현재 상영작, 크레딧, 포스터 및 시청 제공업체 데이터를 사용하여 순위가 매겨진 영화 목록을 작성합니다.

브라우저 데모에는 배포된 /mcp 경로를 호출하고 예상되는 도구 계약을 확인하며 compare_movies, find_where_to_watch, get_weekend_watchlist를 샘플링하는 MCP 도구 표면 패널도 포함되어 있습니다.

전체 브라우저 앱, 배포된 Worker, 액세스 토큰 및 MCP 핸드오프에 대해서는 docs/weekend-watch-concierge.md를 참조하세요.

배포

1. Cloudflare에 로그인:

   npx wrangler login

2. TMDB 키를 Worker 비밀로 저장:

   npx wrangler secret put TMDB_API_KEY

3. 배포를 공유하기 전에 액세스 토큰을 Worker 비밀로 저장:

   npx wrangler secret put ACCESS_TOKEN

   ACCESS_TOKEN이 설정되면 POST /api/concierge 및 POST /mcp는 다음을 요구합니다:

   Authorization: Bearer <your-access-token>

4. Worker 번들 확인:

   npm run worker:dry-run

5. 배포:

   npm run worker:deploy

Cloudflare는 다음과 같은 URL을 출력합니다:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev

원격 클라이언트에서 이 MCP 엔드포인트를 사용하세요:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

이 브라우저 데모 URL을 사용하세요:

https://tmdb-mcp.<your-workers-subdomain>.workers.dev/

Claude / Cowork에서 연결

Claude 사용자 지정 커넥터의 경우:

1. Claude 설정 열기: Customize -> Connectors.

2. + 클릭 -> Add custom connector.

3. 배포된 Worker MCP URL 사용:

   https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp

4. 대화에서 커넥터를 활성화하고 다음과 같은 TMDB 질문을 하세요:

   What movies are trending this week?

여전히 로컬 명령이 필요한 Claude Desktop 버전 또는 MCP 클라이언트의 경우 mcp-remote 프록시를 사용하세요:

{
  "mcpServers": {
    "tmdb-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

보안 참고 사항

ACCESS_TOKEN이 구성되지 않은 경우 Worker는 쉬운 개인 테스트를 위해 인증 없이 작동합니다. Worker URL을 가진 사람은 누구나 읽기 전용 TMDB 도구를 호출하고 TMDB API 할당량을 소비할 수 있습니다. 이를 자신의 계정 외부로 공유하기 전에 ACCESS_TOKEN을 구성하거나 Cloudflare Access를 사용하세요.

주말 시청 컨시어지

오프라인 컨시어지 테스트 실행:

npm test

이것은 TypeScript 프로젝트를 빌드하고, 작은 로컬 TMDB 호환 픽스처 서버를 시작하며, createWeekendConcierge가 상영 시간 필터를 준수하면서 요청된 스트리밍 서비스 일치 항목의 순위를 먼저 매기는지 확인합니다. TMDB API 키가 필요하지 않습니다.

로컬에서 Worker 실행:

npm run worker:dev

이것은 .env의 로컬 값을 추적되지 않는 .dev.vars 파일로 동기화하여 Wrangler가 로컬 개발 중에 Worker에 TMDB_API_KEY를 노출할 수 있도록 합니다.

보호된 로컬 테스트를 위해 .env에 ACCESS_TOKEN을 추가하세요. 브라우저 앱에는 액세스 토큰 필드가 있으며 스모크 스크립트는 셸 환경에서 ACCESS_TOKEN 또는 TMDB_MCP_ACCESS_TOKEN을 읽을 수 있습니다.

열기:

http://127.0.0.1:8787/

로컬 Worker가 실행된 후 컨시어지 API 스모크 테스트:

npm run smoke:concierge

원격 MCP 엔드포인트를 스모크 테스트하고 에이전트 대상 컨시어지 도구 호출:

node scripts/remote-mcp-smoke.mjs http://127.0.0.1:8787/mcp --call-concierge

보호된 배포의 경우:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/remote-mcp-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --call-concierge

또는 배포된 Worker 테스트:

node scripts/concierge-smoke.mjs https://tmdb-mcp.<your-workers-subdomain>.workers.dev

앱 사용:

• 순위가 매겨진 영화 선택을 위한 POST /api/concierge

• 배포 상태를 위한 GET /health

• 원격 MCP 클라이언트를 위한 POST /mcp

에이전트는 다음을 사용하여 get_weekend_watchlist를 호출할 수 있습니다:

• mood: crowd, thriller, thoughtful, funny, family 또는 mindbend

• country: 시청 제공업체 지역 (예: IN 또는 US)

• language: 원어 코드 (예: en, hi, ta, te 또는 any)

• runtime: 최대 분 (예: 120, 150 또는 any)

• minRating: 최소 TMDB 평점

• services: 선호 스트리밍 서비스

Cloudflare MCP 데모 워크플로우

구체적인 엔드투엔드 에이전트 워크플로우를 보려면 현재 상영작 후속 데모를 실행하세요. 원격 클라이언트가 사용하는 것처럼 MCP 서버를 사용합니다:

1. 선택한 지역의 현재 극장 탐색을 위한 get_now_playing

2. 선택한 제목에 대한 get_movie_details

3. 시청 가능 여부를 위한 get_watch_providers

4. get_recommendations (매우 새로운 제목의 경우 get_similar_movies 대체)

5. 후속 가용성 확인을 위한 get_watch_providers

로컬 stdio MCP:

npm run build
set -a && source ./.env && set +a && npm run demo:now-playing -- --region US

Cloudflare 호스팅 MCP:

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/now-playing-follow-on-demo.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --region US

스크립트는 최종 아티팩트를 여기에 작성합니다:

examples/now-playing-follow-on-demo.md

npm run install:local의 기능

설치 프로그램은 plugins/tmdb/scripts/run-server.sh에 있는 저장소 소유 런처를 사용합니다.

Codex의 경우:

• 런처를 MCP 서버로 등록

• 로컬 TMDB 플러그인 페이로드를 설치하여 플러그인 UI에 표시되도록 함

Claude Desktop의 경우:

• 동일한 런처를 로컬 MCP 서버로 등록

다음 항목을 업데이트합니다:

• ~/.codex/config.toml

• ~/.codex/.tmp/plugins/.agents/plugins/marketplace.json

• ~/.codex/plugins/cache/openai-curated/tmdb/...

• ~/Library/Application Support/Claude/claude_desktop_config.json

런처는 셸 환경 또는 저장소 .env 파일에서 TMDB_API_KEY를 읽습니다.

Claude Desktop 사용법

수동 설정을 선호하는 경우 ~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "tmdb-local": {
      "command": "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh",
      "args": []
    }
  }
}

설정을 편집한 후 Claude Desktop을 다시 시작하세요.

Codex 사용법

설치 프로그램은 ~/.codex/config.toml에 다음 블록을 추가합니다:

[mcp_servers.tmdb_local]
command = "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh"

[plugins."tmdb@openai-curated"]
enabled = true

설정을 편집한 후 Codex를 다시 시작하세요. 새로운 Codex 세션에서 TMDB가 플러그인 목록에 나타나고 mcp__tmdb__ 네임스페이스를 기여해야 합니다.

검증

오프라인 스모크 테스트:

TMDB_API_KEY=dummy node plugins/tmdb/scripts/smoke-test.mjs

온라인 스모크 테스트:

set -a && source ./.env && set +a && node plugins/tmdb/scripts/smoke-test.mjs --online

플러그인 문서

플러그인 패키징, 로컬 설치 동작 및 Codex 관련 참고 사항은 plugins/tmdb/README.md를 참조하세요.

BizClaw / NanoClaw 사용법

에이전트 컨테이너에 내장되어 있습니다. .env 파일에 TMDB_API_KEY를 설정하기만 하면 됩니다. 별도의 구성이 필요하지 않습니다.

예시 프롬프트

"What's trending in movies this week?"
"Find me Thriller movies from 2023"
"Who is Christopher Nolan and what has he directed?"
"Where can I watch Inception in India?"
"Get details for movie ID 550 (Fight Club)"
"Find movies similar to Interstellar"
"What are the trending TV shows right now?"

라이선스

MIT