Laksh-star/mcp-server-tmdb

An MCP server for The Movie Database (TMDB) API. It provides movie and TV search, streaming availability, cast and crew details, and recommendations for assistants such as Codex and Claude Desktop.
For the architecture split between the reusable MCP server and higher-level feature workflows, see USERGUIDE.md.
Tools
Movie Discovery
- **get_weekend_watchlist** — Ranked weekend shortlist by mood, country, language, runtime, rating, and services
- **plan_watch_party** — Group movie-night plan with a primary pick, backup, wildcard, party-fit reasons, provider availability, and avoided-title filtering
- **build_franchise_watch_order** — Franchise/universe guide with release order, suggested order, total runtime, and provider-aware notes
- **build_collection_gap_plan** — Franchise completion plan with watched/missing entries, remaining runtime, provider availability, and completion path
- **recommend_from_taste_profile** — Recommendations from liked/disliked titles with provider-aware scoring, match reasons, and cautions
- **build_release_calendar_watchlist** — Release-window watchlist with upcoming movies, provider-ready picks, broad-room baselines, and watch-later scoring
- **search_movies** — Search by title/keywords → titles, IDs, ratings, overviews
- **get_trending** — Top 10 trending movies (timeWindow: "day" | "week")
- **get_weekly_trending_by_language** — Weekly trending movies grouped by original language into English, Hindi, and Telugu
- **search_by_genre** — Movies by genre name, optional year filter
- **advanced_search** — Filter by genre, year, min rating, sort, language
- **search_by_keyword** — Find movies by theme/keyword (e.g. "zombie", "heist")
Movie Details
- **get_movie_details** — Full details: cast, crew, runtime, genres, reviews (by movieId)
- **compare_movies** — Side-by-side comparison for 2-5 movie IDs with ratings, runtime, cast, director, providers, and best-fit notes
- **get_recommendations** — Top 5 recommendations based on a movie ID
- **get_similar_movies** — Similar movies via TMDB's similarity algorithm
- **get_watch_providers** — Streaming/rental/purchase availability by country (default: IN)
- **find_where_to_watch** — Search 1-5 movie titles and return streaming/rental/purchase availability with preferred-service matches
TV Shows
- **search_tv_shows** — Search TV series by title
- **get_trending_tv** — Top 10 trending TV shows (timeWindow: "day" | "week")
People
- **search_person** — Find actors, directors, crew by name → ID + known works
- **get_person_details** — Full bio + filmography (movies + TV) by personId
- **build_person_watch_path** — Actor/director watch path with best-rated, available-now, recent, and starter picks
Resources
- tmdb:///movie/ — Full movie details in JSON (title, cast, director, reviews, poster URL)
Quick Start
1. Get a TMDB API key at themoviedb.org → Account Settings → API
2. Clone, install, and build:
3. Create a local env file and add your TMDB key:
4. Install the local Codex and Claude Desktop integration:
5. Restart Codex or Claude Desktop if already open.
6. Verify with a prompt like:
In Codex, a fresh session should show TMDB in the plugin list and expose the mcp__tmdb__ namespace.
Tool Surface Smoke
Use this smoke test after adding or merging tools. It verifies the expected MCP tool contract and calls the main workflow tools: compare_movies, find_where_to_watch, get_weekend_watchlist, plan_watch_party, build_franchise_watch_order, build_collection_gap_plan, recommend_from_taste_profile, and build_person_watch_path.
Local stdio MCP:
Cloudflare-hosted MCP:
The script writes a compact verification artifact to:
To avoid tool bloat, prefer adding workflow tools that combine multiple TMDB calls into a useful user decision. Keep raw endpoint-style tools only when they are broadly reusable primitives.
Weekly Trending Language Demo
This repo includes a small shareable demo that calls the MCP tool get_weekly_trending_by_language, which fetches live TMDB weekly trending movies and groups the current first page by TMDB original_language.