moviefinder-mcp
moviefinder-mcp
The Movie Database (TMDB) API를 래핑하는 MCP 서버입니다. @modelcontextprotocol/sdk와 stdio 전송 방식을 사용하여 구축되었습니다.
도구
도구 | 설명 |
| 제목으로 영화 검색, 선택적 |
| 제목으로 TV 프로그램 검색. |
| 주요 출연진, 감독, 예고편을 포함한 전체 영화 상세 정보. |
| 특정 영화에 대한 TMDB 추천. |
| 특정 영화와 유사한 영화. |
|
|
| 영화의 스트리밍 / 대여 / 구매 제공업체 (기본 국가 |
| 장르 이름, 최소 평점, 연도, 정렬 순서로 영화 탐색. |
모든 도구는 요약된 JSON(id, 제목, 연도, 개요, 평점, 포스터 URL 등)을 반환하며, 불필요한 원시 TMDB 필드는 제거됩니다.
Related MCP server: wizzy-mcp-tmdb
설정
1. TMDB API 토큰 받기
https://www.themoviedb.org/ 에서 무료 계정을 만듭니다.
https://www.themoviedb.org/settings/api 를 방문하여 API Read Access Token (v4)을 복사합니다. 이는 긴 JWT이며, v3 API 키가 아닙니다.
2. 설치 및 빌드
npm install
npm run build3. 환경 설정
.env.example을 .env로 복사하고 토큰을 붙여넣습니다:
cp .env.example .envTMDB_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.jsonWindows:
%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 도구가 모든 대화에서 나타납니다.
스크립트
스크립트 | 설명 |
| TypeScript를 |
| 컴파일된 서버( |
| TypeScript 감시 모드. |
오류 처리
서버는 일반적인 TMDB 오류에 대해 유용한 메시지를 반환합니다:
401 — 토큰 누락 또는 잘못된 키 유형 (v4 읽기 액세스 토큰이어야 함).
404 — 요청한 영화 / 리소스가 존재하지 않음.
429 — 속도 제한 초과;
Retry-After값이 존재할 경우 포함됨.
참고 사항
장르 목록은
/genre/movie/list에서 한 번 가져와 메모리에 캐시됩니다.포스터 URL은
https://image.tmdb.org/t/p/w500을 사용합니다.데이터베이스나 로깅 프레임워크는 의도적으로 사용하지 않았습니다.
Available Tools
8 toolsdiscover_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).
get_trendingC
Get trending movies, TV shows, or both.
Inputs: media_type (required), time_window (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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Unofficial Movies MCP — wraps iTunes Search API (movies, free, no auth) and TVmaze API (TV shows…
Unlock a world of television with the TV Maze MCP server. Effortlessly search for shows by name or
OMDb MCP — IMDB-derived movie / TV / episode data (BYO key)
Related MCP Servers
- AlicenseDqualityDmaintenanceAn 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.5MIT
- AlicenseAqualityDmaintenanceA MCP server for The Movie Database API that enables AI assistants to search and retrieve movie, TV show, and person information.2313 npm4MIT
- FlicenseAqualityDmaintenanceAn 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-
- FlicenseNot gradedqualityCmaintenanceA robust MCP server that wraps The Movie Database API, enabling LLMs to search movies, get details, popular movies, and recommendations.-