TMDB MCP 서버

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

도구

영화 탐색

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

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

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

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

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

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

영화 상세 정보

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

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

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

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

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: TMDB MCP Server

빠른 시작

1. themoviedb.org → 계정 설정 → API에서 TMDB 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__ 네임스페이스가 노출되어야 합니다.

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 탐색, 인기 영화, 현재 상영작, 크레딧, 포스터 및 시청 제공자 데이터를 사용하여 순위가 매겨진 영화 목록을 작성합니다.

전체 브라우저 앱, 배포된 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를 사용하세요.

주말 시청 컨시어지

로컬에서 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: 선호하는 스트리밍 서비스

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