TMDB MCP Server

by Laksh-star

51 stars

213 downloads

Not rated

GitHub

About

Integrates with The Movie Database (TMDB) API to provide movie information, search capabilities, and recommendations.

Details

Author: Laksh-star
Repository: Laksh-star/mcp-server-tmdb
GitHub stars: 51
Downloads: 213
License: MIT License
Categories: Search, Media, Other, AI, Design, Developer Tools, API, Database, Infrastructure, Knowledge Base
Tags: #entertainment

- Search movies, TV shows, and people by title or keyword
- View trending movies and TV shows (daily/weekly)
- Filter movies by genre, year, rating, and language
- Get detailed movie and person information
- Compare 2–5 movies side-by-side
- Find streaming, rental, and purchase availability per country
- Workflow tools: weekend watchlist, watch party planning, franchise watch order, collection gap plan, and taste‑based recommendations

Setting up with Highlight

Follow these steps to add this server as a custom Highlight plugin:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name TMDB MCP Server

Command (node, npx, python, etc.) npx
Arguments
- Argument 1 mcp-remote
- Argument 2 https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

1. Log in to Cloudflare:

   npx wrangler login

2. Store your TMDB key as a Worker secret:

   npx wrangler secret put TMDB_API_KEY

3. Store an access token as a Worker secret before sharing the deployment:

   npx wrangler secret put ACCESS_TOKEN

When ACCESS_TOKEN is set, POST /api/concierge and POST /mcp require:

   Authorization: Bearer <your-access-token>

4. Check the Worker bundle:

   npm run worker:dry-run

5. Deploy:

   npm run worker:deploy

Cloudflare will print a URL like:

```text

`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 to find titles, IDs, ratings, and overviews.

`get_trending`

Top 10 trending movies with a specified time window, either 'day' or 'week'.

`get_weekly_trending_by_language`

Weekly trending movies grouped by original language into English, Hindi, and Telugu.

`search_by_genre`

Retrieve movies by genre name with an optional year filter.

`advanced_search`

Filter movies by genre, year, minimum rating, sort order, and language.

`search_by_keyword`

Find movies by a specific theme or keyword (e.g., 'zombie', 'heist').

`get_movie_details`

Retrieve full details of a movie including cast, crew, runtime, genres, and reviews based on movieId.

`compare_movies`

Side-by-side comparison for 2-5 movie IDs with details like ratings, runtime, cast, director, and providers.

`get_recommendations`

Get top 5 recommendations based on a specific movie ID.

`get_similar_movies`

Find similar movies using TMDB's similarity algorithm.

`get_watch_providers`

Check streaming, rental, and purchase availability by country (default is IN).

`find_where_to_watch`

Search 1-5 movie titles to return their streaming, rental, and purchase availability with preferred-service matches.

`search_tv_shows`

Search for TV series by title.

`get_trending_tv`

Get top 10 trending TV shows with a specified time window, either 'day' or 'week'.

`search_person`

Find actors, directors, and crew by name, returning their ID and known works.

`get_person_details`

Retrieve full bio and filmography (movies and TV) by personId.

`build_person_watch_path`

Create a watch path for an actor or director, including best-rated, available-now, recent, and starter picks.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

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

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, seeUSERGUIDE.md.

- 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")

- get_movie_details— Full details: cast, crew, runtime, genres, reviews (bymovieId)
- 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

- search_tv_shows— Search TV series by title
- get_trending_tv— Top 10 trending TV shows (timeWindow: "day" | "week")

- search_person— Find actors, directors, crew by name → ID + known works
- get_person_details— Full bio + filmography (movies + TV) bypersonId
- build_person_watch_path— Actor/director watch path with best-rated, available-now, recent, and starter picks

- tmdb:///movie/<id>— Full movie details in JSON (title, cast, director, reviews, poster URL)
-

Get a TMDB API key at themoviedb.org→ Account Settings → API

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

Create a local env file and add your TMDB key:

Install the local Codex and Claude Desktop integration:

Restart Codex or Claude Desktop if already open.

In Codex, a fresh session should showTMDBin the plugin list and expose themcp__tmdb__namespace.

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, andbuild_person_watch_path.

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

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

This repo includes a small shareable demo that calls the MCP toolget_weekly_trending_by_language, which fetches live TMDB weekly trending movies and groups the current first page by TMDBoriginal_language.

Run it against the local stdio MCP server:

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

After deploying this version of the Worker, run the same demo against a remote MCP endpoint:

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

If the deployment is intentionally authless for personal testing, omitTMDB_MCP_ACCESS_TOKEN.

This repo also includes a script-first weekly radar. It chains existing MCP tools into a Markdown artifact with movie trends, TV trends, language momentum, action-ready picks, family-safe picks, and a taste-profile probe.

npm run build set -a && source ./.env && set +a && npm run demo:weekly-radar -- --country US

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/weekly-streaming-radar.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US

The release calendar is available as the MCP toolbuild_release_calendar_watchlist. The demo script calls that tool and writes a Markdown artifact for release-window scanning, watch-later candidates, provider-ready picks, and broad-room baselines.

npm run build set -a && source ./.env && set +a && npm run demo:release-calendar -- --country US --days 90

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/release-calendar-watchlist.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --days 90

The provider monitor is script-first because it needs persisted state. It callsfind_where_to_watch, compares the current provider list against a JSON snapshot, and writes a Markdown delta report showing new, removed, unchanged, and missing provider availability.

npm run build set -a && source ./.env && set +a && npm run demo:provider-monitor -- --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/provider-change-monitor.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --country US --titles "The Matrix,Inception" --services "Netflix,Prime Video"

examples/provider-change-monitor.md examples/provider-change-snapshot.json

The collection gap finder script now calls the promoted MCP toolbuild_collection_gap_planand writes a repeatable Markdown completion report with watched entries, missing entries, remaining runtime, provider availability, and a shortest completion path.

npm run build set -a && source ./.env && set +a && npm run demo:collection-gaps -- --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

TMDB_MCP_ACCESS_TOKEN=<your-access-token> node scripts/collection-gap-finder.mjs --mcp-url https://tmdb-mcp.<your-workers-subdomain>.workers.dev/mcp --franchise "The Matrix" --watched "The Matrix" --country US --services "Netflix,Prime Video"

This repo can also run as a remote MCP server on Cloudflare Workers. The remote server exposes the same TMDB tools at/mcpover Streamable HTTP, so Claude, Cowork, Claude Desktop connectors, and other remote-MCP clients can connect to a public URL.

The existing local stdio server remains unchanged for Codex and local Claude Desktop use. The Cloudflare entrypoint issrc/worker.ts.

The Worker also serves a browser demo at/:Weekend Watch Concierge. It supports solo picks and Watch Party mode, then builds a ranked movie shortlist using TMDB discovery, trending, now-playing, credits, posters, and watch-provider data. The browser app also includes a Help drawer for Cloudflare usage and a Workflow Demos panel with commands for script-first artifacts such as Weekly Streaming Radar, Provider Change Monitor, and Collection Gap Finder.

The browser demo also includes anMCP tool surfacepanel that calls the deployed/mcproute, verifies the expected tool contract, and samplescompare_movies,find_where_to_watch,get_weekend_watchlist,plan_watch_party,build_franchise_watch_order,build_collection_gap_plan,recommend_from_taste_profile, andbuild_person_watch_path.

For the complete browser app, deployed Worker, access-token, and MCP handoff, seedocs/weekend-watch-concierge.md.

Store an access token as a Worker secret before sharing the deployment:

WhenACCESS_TOKENis set,POST /api/conciergeandPOST /mcprequire:

Authorization: Bearer <your-access-token>

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

Use this MCP endpoint in remote clients:

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

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

- Open Claude settings:Customize->Connectors.
- Click+->Add custom connector.
- Use the deployed Worker MCP URL:

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

For Claude Desktop versions or MCP clients that still require a local command, use themcp-remoteproxy:

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

IfACCESS_TOKENis not configured, the Worker is authless for easy personal testing. Anyone who has the Worker URL can call the read-only TMDB tools and consume your TMDB API quota. KeepACCESS_TOKENconfigured or use Cloudflare Access before sharing this beyond your own accounts.

This builds the TypeScript project, starts a tiny local TMDB-compatible fixture server, and verifies thatcreateWeekendConciergeranks a requested streaming-service match first while respecting the runtime filter. It does not need a TMDB API key.

This syncs local values from.envinto an untracked.dev.varsfile so Wrangler can exposeTMDB_API_KEYto the Worker during local development.

For protected local testing, addACCESS_TOKENto.env. The browser app has an access-token field and the smoke scripts can readACCESS_TOKENorTMDB_MCP_ACCESS_TOKENfrom the shell environment.

Smoke test the concierge API after the local Worker is running:

Smoke test the remote MCP endpoint and call the agent-facing concierge tool:

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

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

- POST /api/conciergefor ranked movie picks
- POST /api/collection-gap-planfor Planning Lab collection gaps
- POST /api/taste-profilefor Planning Lab taste-fit recommendations
- POST /api/person-watch-pathfor Planning Lab person watch paths
- GET /healthfor deployment health
- POST /mcpfor remote MCP clients

Agents can callget_weekend_watchlistwith:

- mood:crowd,thriller,thoughtful,funny,family, ormindbend
- country: watch-provider region, for exampleINorUS
- language: original language code, for exampleen,hi,ta,te, orany
- runtime: maximum minutes, for example120,150, orany
- minRating: minimum TMDB rating
- services: preferred streaming services
- familySafe: set totrueto exclude common mature genres when TMDB genre data is available

Agents can callplan_watch_partywhen the decision is for a group. It accepts:

- moods: one to three values fromcrowd,thriller,thoughtful,funny,family, ormindbend
- groupSize: number of people watching
- country,language,runtime,minRating, andservices: same meaning as the weekend watchlist
- avoidTitles: titles the group has already seen or wants excluded
- familySafe: set totrueto exclude common mature genres when TMDB genre data is available

Agents can callbuild_franchise_watch_orderfor a collection or universe guide. It accepts:

- query: franchise or collection name, for exampleThe Matrix,Dune,Batman, orMission Impossible
- country: watch-provider region, for exampleINorUS
- maxMovies: maximum collection entries to include, from 2 to 20

Agents can callbuild_collection_gap_planfor franchise completion planning. It accepts:

- query: franchise or collection name
- watchedTitles: watched titles or TMDB movie IDs
- country: watch-provider region, for exampleINorUS
- services: preferred streaming services
- maxMovies: maximum collection entries to include, from 2 to 20

Agents can callrecommend_from_taste_profilefor personalized recommendations. It accepts:

- likedTitles: one to five movies the user likes
- dislikedTitles: optional movies the user dislikes or wants to avoid stylistically
- country,services,language,runtime, andminRating: filters and watch-now preferences
- maxResults: number of recommendations to return, from 3 to 10

Agents can callbuild_person_watch_pathfor an actor, director, writer, or crew member. It accepts:

- name: person name, for exampleKeanu ReevesorChristopher Nolan
- country: watch-provider region, for exampleINorUS
- services: preferred streaming services
- maxTitles: number of watch-path entries to return, from 3 to 8

For a concrete end-to-end agent workflow, run the now-playing follow-on demo. It uses the MCP server as a remote client would:
- get_now_playingfor current theater discovery in a selected region
- get_movie_detailsfor the selected title
- get_watch_providersfor watch-now availability
- get_recommendations, withget_similar_moviesfallback for very new titles
- get_watch_providersfor follow-on availability checks

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

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

The script writes the final artifact here:

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get_weekend_watchlist

plan_watch_party

build_franchise_watch_order

build_collection_gap_plan

recommend_from_taste_profile

build_release_calendar_watchlist

search_movies

get_trending

get_weekly_trending_by_language

search_by_genre

advanced_search

search_by_keyword

get_movie_details

compare_movies

get_recommendations

get_similar_movies

get_watch_providers

find_where_to_watch

search_tv_shows

get_trending_tv

search_person

get_person_details

build_person_watch_path

Claude Desktop / Cursor

Linux

Macos

Windows

Install

More like this

Sequential Thinking

Brave Search

Filesystem

EverArt

Google Maps

Google Drive

`get_weekend_watchlist`

`plan_watch_party`

`build_franchise_watch_order`

`build_collection_gap_plan`

`recommend_from_taste_profile`

`build_release_calendar_watchlist`

`search_movies`

`get_trending`

`get_weekly_trending_by_language`

`search_by_genre`

`advanced_search`

`search_by_keyword`

`get_movie_details`

`compare_movies`

`get_recommendations`

`get_similar_movies`

`get_watch_providers`

`find_where_to_watch`

`search_tv_shows`

`get_trending_tv`

`search_person`

`get_person_details`

`build_person_watch_path`