Skip to main content
Glama
moviefinder-mcp

moviefinder-mcp

moviefinder-mcp

The Movie Database (TMDB) API를 래핑하는 MCP 서버입니다. @modelcontextprotocol/sdk와 stdio 전송 방식을 사용하여 구축되었습니다.

도구

도구

설명

search_movies

제목으로 영화 검색, 선택적 year 필터 사용 가능.

search_tv

제목으로 TV 프로그램 검색.

get_movie_details

주요 출연진, 감독, 예고편을 포함한 전체 영화 상세 정보.

get_recommendations

특정 영화에 대한 TMDB 추천.

get_similar

특정 영화와 유사한 영화.

get_trending

day 또는 week 단위의 movie / tv / all 트렌드.

where_to_stream

영화의 스트리밍 / 대여 / 구매 제공업체 (기본 국가 US).

discover_movies

장르 이름, 최소 평점, 연도, 정렬 순서로 영화 탐색.

모든 도구는 요약된 JSON(id, 제목, 연도, 개요, 평점, 포스터 URL 등)을 반환하며, 불필요한 원시 TMDB 필드는 제거됩니다.

Related MCP server: wizzy-mcp-tmdb

설정

1. TMDB API 토큰 받기

  1. https://www.themoviedb.org/ 에서 무료 계정을 만듭니다.

  2. https://www.themoviedb.org/settings/api 를 방문하여 API Read Access Token (v4)을 복사합니다. 이는 긴 JWT이며, v3 API 키가 아닙니다.

2. 설치 및 빌드

npm install
npm run build

3. 환경 설정

.env.example을 .env로 복사하고 토큰을 붙여넣습니다:

cp .env.example .env
TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. 서버 실행

npm start

이 서버는 stdio를 통해 MCP와 통신하며, 대화형으로 실행되는 것이 아니라 MCP 클라이언트(예: Claude Desktop)에 의해 실행되도록 설계되었습니다.

Claude Desktop에 등록

claude_desktop_config.json에 항목을 추가합니다:

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

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "moviefinder": {
      "command": "node",
      "args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

설정을 편집한 후 Claude Desktop을 다시 시작하세요. 그러면 moviefinder 도구가 모든 대화에서 나타납니다.

스크립트

스크립트

설명

npm run build

TypeScript를 dist/로 컴파일합니다.

npm start

컴파일된 서버(node dist/index.js)를 실행합니다.

npm run dev

TypeScript 감시 모드.

오류 처리

서버는 일반적인 TMDB 오류에 대해 유용한 메시지를 반환합니다:

  • 401 — 토큰 누락 또는 잘못된 키 유형 (v4 읽기 액세스 토큰이어야 함).

  • 404 — 요청한 영화 / 리소스가 존재하지 않음.

  • 429 — 속도 제한 초과; Retry-After 값이 존재할 경우 포함됨.

참고 사항

  • 장르 목록은 /genre/movie/list에서 한 번 가져와 메모리에 캐시됩니다.

  • 포스터 URL은 https://image.tmdb.org/t/p/w500을 사용합니다.

  • 데이터베이스나 로깅 프레임워크는 의도적으로 사용하지 않았습니다.

Available Tools

8 tools
discover_moviesC

Discover movies by genre name, minimum rating, year, and sort order. Genre is resolved by name (e.g. 'Action').

Inputs: genre, min_rating, year, sort_by.

get_movie_detailsA

Get full details for a movie, including top cast, directors, and trailer.

Inputs: movie_id (required).

get_recommendationsC

Get TMDB recommendations for a given movie.

Inputs: movie_id (required).

get_similarC

Get movies similar to a given movie.

Inputs: movie_id (required).

search_moviesA

Search TMDB for movies by title. Optionally filter by release year.

Inputs: query (required), year.

search_tvB

Search TMDB for TV shows by title.

Inputs: query (required).

where_to_streamA

Find streaming, rental, and purchase providers for a movie in a given country (default US). Data sourced from JustWatch via TMDB.

Inputs: movie_id (required), country_code.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct action: discover by criteria, get full details, get recommendations, get similar, get trending, search movies, search TV, and find streaming providers. No meaningful overlap exists.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., discover_movies, get_movie_details, search_tv). 'where_to_stream' is a minor deviation but still clearly readable.

    Tool Count5/5

    8 tools cover the main use cases for a movie/TV finder: discovery, search, details, trends, recommendations, similar, and streaming info. The scope is well-balanced.

    Completeness4/5

    The set covers most core movie operations, but lacks get_tv_details for TV shows. Other gaps like user ratings or reviews are acceptable for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      D
      quality
      D
      maintenance
      An MCP server that allows users to search for movies, get detailed information, receive genre-based recommendations, and discover popular/trending films using OMDb and TMDb APIs.
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A MCP server for The Movie Database API that enables AI assistants to search and retrieve movie, TV show, and person information.
      23
      13 npm
      4
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      An MCP server that wraps the TMDB API, enabling search of movies and TV shows, retrieval of details, trending titles, recommendations, and streaming provider information.
      8
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      A robust MCP server that wraps The Movie Database API, enabling LLMs to search movies, get details, popular movies, and recommendations.
      -