The Movie Database (TMDb) MCP Server for Claude Code 15 tools — connect in under 2 minutes
Claude Code is Anthropic's agentic CLI for terminal-first development. Add The Movie Database (TMDb) as an MCP server in one command and Claude Code will discover every tool at runtime — ideal for automation pipelines, CI/CD integration, and headless workflows via the Vinkius.
ASK AI ABOUT THIS MCP SERVER
Vinkius supports streamable HTTP and SSE.
Vinkius Desktop App
The modern way to manage MCP Servers — no config files, no terminal commands. Install The Movie Database (TMDb) and 2,500+ MCP Servers from a single visual interface.
# Your Vinkius token — get it at cloud.vinkius.com
claude mcp add the-movie-database-tmdb --transport http "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
* Every MCP server runs on Vinkius-managed infrastructure inside AWS - a purpose-built runtime with per-request V8 isolates, Ed25519 signed audit chains, and sub-40ms cold starts optimized for native MCP execution. See our infrastructure
About The Movie Database (TMDb) MCP Server
Connect The Movie Database (TMDb) to any AI agent and unlock the world's most comprehensive movie and TV show database through natural conversation. TMDb is the same database used by major streaming platforms, media players, and entertainment apps worldwide.
Claude Code registers The Movie Database (TMDb) as an MCP server in a single terminal command. Once connected, Claude Code discovers all 15 tools at runtime and can call them headlessly — ideal for CI/CD pipelines, cron jobs, and automated workflows where The Movie Database (TMDb) data drives decisions without human intervention.
What you can do
- Movie Search — Search any movie by title, keyword, or phrase with release dates, ratings, overviews, and poster images
- TV Show Search — Find TV shows and series with season counts, episode information, network details, and air dates
- Unified Multi-Search — Search movies, TV shows, and people simultaneously for broad entertainment queries
- Complete Movie Details — Get full movie metadata including budget, revenue, runtime, genres, production studios, taglines, and IMDb cross-references
- Cast & Crew Information — Retrieve complete cast lists with actor characters and crew details (directors, writers, producers, cinematographers)
- Trailers & Videos — Access official trailers, teasers, behind-the-scenes clips, and promotional videos (YouTube links)
- Popular & Top Rated — Browse currently popular movies/TV shows and all-time highest-rated content
- Trending Content — See what is trending today or this week across movies, TV shows, and people
- Advanced Movie Discovery — Filter movies by genre, year, minimum rating, production studio (e.g., Warner Bros., Marvel), and sort by popularity, rating, or revenue
- Movie Recommendations — Get similar movie suggestions based on a specific film using TMDb's recommendation algorithm
- Person Profiles — Search for actors, directors, and crew with biographies, filmographies, and combined credits
- External ID Lookup — Convert IMDb IDs (tt0111161), TVDb IDs, and other external identifiers to TMDb entries
- Genre Reference — Access the complete genre database with IDs for advanced filtering
The The Movie Database (TMDb) MCP Server exposes 15 tools through the Vinkius. Connect it to Claude Code in under two minutes — no API keys to rotate, no infrastructure to provision, no vendor lock-in. Your configuration, your data, your control.
How to Connect The Movie Database (TMDb) to Claude Code via MCP
Follow these steps to integrate the The Movie Database (TMDb) MCP Server with Claude Code.
Install Claude Code
Run npm install -g @anthropic-ai/claude-code if not already installed
Add the MCP Server
Run the command above in your terminal
Verify the connection
Run claude mcp to list connected servers, or type /mcp inside a session
Start using The Movie Database (TMDb)
Ask Claude: "Using The Movie Database (TMDb), show me..." — 15 tools are ready
Why Use Claude Code with the The Movie Database (TMDb) MCP Server
Claude Code provides unique advantages when paired with The Movie Database (TMDb) through the Model Context Protocol.
Single-command setup: `claude mcp add` registers the server instantly — no config files to edit or applications to restart
Terminal-native workflow means MCP tools integrate seamlessly into shell scripts, CI/CD pipelines, and automated DevOps tasks
Claude Code runs headlessly, enabling unattended batch processing using The Movie Database (TMDb) tools in cron jobs or deployment scripts
Built by the same team that created the MCP protocol, ensuring first-class compatibility and the fastest adoption of new protocol features
The Movie Database (TMDb) + Claude Code Use Cases
Practical scenarios where Claude Code combined with the The Movie Database (TMDb) MCP Server delivers measurable value.
CI/CD integration: embed The Movie Database (TMDb) tool calls in your deployment pipeline to validate configurations or fetch secrets before shipping
Headless batch processing: schedule Claude Code to query The Movie Database (TMDb) nightly and generate reports without human intervention
Shell scripting: pipe The Movie Database (TMDb) outputs into other CLI tools for data transformation, filtering, and aggregation
Infrastructure monitoring: run Claude Code in a cron job to query The Movie Database (TMDb) status endpoints and alert on anomalies
The Movie Database (TMDb) MCP Tools for Claude Code (15)
These 15 tools become available when you connect The Movie Database (TMDb) to Claude Code via MCP:
discover_movies
Find movies matching very specific criteria. Available filters: genre (genre IDs, comma-separated for OR), year, sortBy (popularity, rating, revenue, release date), vote_average.gte (minimum rating), with_companies (studio IDs, comma-separated), with_keywords (keyword IDs), primary_release_date.gte/lte (date range YYYY-MM-DD). Sort options: popularity.desc, popularity.asc, release_date.desc, release_date.asc, vote_average.desc, vote_average.asc, revenue.desc, revenue.asc, title.asc, title.desc. Use this for complex queries like "action movies from 2024 with rating above 7", "Warner Bros movies from the last year", or "horror movies sorted by rating". Genre IDs can be obtained from the get_genres tool. Company ID 17 = Warner Bros, 420 = Marvel Studios, 33 = Universal, etc. Discover movies with advanced filtering by genre, year, rating, studio, and more
find_by_external_id
The externalSource parameter must be one of: "imdb_id", "tvdb_id", "freebase_mid", "freebase_id", "tvrage_id", "wikidata_id". Returns matching movies, TV shows, and/or people from TMDb that have this external ID. Use this when you have an IMDb ID (like "tt0111161" for Shawshank Redemption) and want to find the corresponding TMDb entry. Common use case: converting IMDb IDs to TMDb IDs for use with other tools. IMDb IDs for movies start with "tt" followed by numbers (e.g., "tt0137523" for Fight Club). Results include all matching items across movies, TV, and people categories. Find movies, TV shows, or people using external IDs (IMDb, TVDb, etc)
get_genres
Each genre includes: id (numeric ID used for filtering in other tools) and name (localized genre name). Use this to get genre IDs needed for the discover_movies tool or to answer questions about available genres. Common movie genres: 28=Action, 12=Adventure, 16=Animation, 35=Comedy, 80=Crime, 18=Drama, 14=Fantasy, 27=Horror, 878=Science Fiction, 53=Thriller, 10749=Romance. The type parameter must be "movie" or "tv". Optional language parameter returns localized genre names. Get the complete list of movie or TV show genres with their IDs
get_movie
Returns: title, overview, runtime, release date, budget, revenue, vote average, vote count, genres, production companies, production countries, spoken languages, status, tagline, homepage, IMDb ID, poster/backdrop image paths, and collection information (if part of a franchise). Use this after a search to get full details about a specific movie. The movieId parameter is the TMDb ID (integer) returned by search_movies or other movie list tools. Optional language parameter returns localized title and overview if available. Get complete details for a specific movie by its TMDb ID
get_movie_credits
Returns two arrays: "cast" (actors with their characters, order, and profile images) and "crew" (directors, producers, writers, cinematographers, editors, composers, etc. with their jobs and departments). Use this when users ask "who starred in...", "who directed...", or want the full cast list of a movie. The movieId is the TMDb ID from search results. Cast includes: actor name, character name, order (billing order), profile image path. Crew includes: name, job title (Director, Producer, Screenplay, etc.), department. Get complete cast and crew information for a specific movie
get_movie_recommendations
TMDb uses an algorithm that considers genre, keywords, cast, crew, and user rating patterns to suggest similar movies that fans of the original might enjoy. Each recommendation includes: title, release date, overview, poster path, vote average, vote count, and TMDb ID. Use this when users ask "if I liked X, what should I watch?", "movies similar to...", or "recommendations for...". The movieId is the TMDb ID of the reference movie. Results are paginated; use the page parameter to get more recommendations. Get movie recommendations based on a specific movie (similar titles)
get_movie_videos
Each video result includes: video key (YouTube ID), site (YouTube), type (Trailer, Teaser, Clip, Behind the Scenes, etc.), name, size (resolution), official status, and publish date. Use this when users want to watch trailers, find official promotional videos, or access movie video content. YouTube videos can be viewed at: https://www.youtube.com/watch?v={key}. The movieId is the TMDb movie ID. Get trailers, teasers, clips, and behind-the-scenes videos for a movie
popular_movies
Each movie includes: title, release date, overview, poster path, vote average, vote count, genre IDs, and TMDb ID. Use this when users ask "what movies are popular now?", "what is trending?", or want movie recommendations. Results are updated regularly based on TMDb user activity. Optional: page for pagination, region (ISO 3166-1 country code like "US", "BR") for country-specific popularity, and language for localized titles and descriptions. Get a list of currently popular movies on TMDb
popular_tv
Popularity is based on user activity, view counts, and trending data. Each TV show includes: name, first air date, overview, poster path, vote average, vote count, genre IDs, number of seasons, number of episodes, origin country, and TMDb ID. Use this when users ask "what TV shows are popular?", "what should I watch?", or want series recommendations. Optional: page for pagination and language for localized titles and descriptions. Get a list of currently popular TV shows on TMDb
search_movies
Returns movie titles, release dates, overview descriptions, poster images, vote averages, and TMDb IDs. Use this when users ask to find movies by title, search for films about a topic, or look up movies from a specific year. The query parameter is required and should be the movie title or search term. Optional parameters: year (YYYY format) to filter by release year, page for pagination (1-500), and language (ISO 639-1 code like "pt-BR", "en-US", "es") to get results in a specific language. Example: query="The Matrix", year="1999" returns the 1999 sci-fi classic. Search for movies by title, keyword, or phrase in the TMDb database
search_multi
Returns results from all three categories with a media_type field indicating the type ("movie", "tv", or "person"). Use this when users provide a general search term and you want to return all relevant results across content types. Ideal for broad queries like "Christopher Nolan" (returns movies directed by him + person profile) or "Star Wars" (returns movies + TV series). The query parameter is required. Optional: page for pagination and language for localized results. Search movies, TV shows, and people simultaneously in the TMDb database
search_tv
Returns TV show names, first air dates, episode counts, overview descriptions, poster images, vote averages, and TMDb IDs. Use this when users ask to find TV series, look up shows by title, or search for programs about a specific topic. The query parameter is required. Optional: year to filter by first air date year, page for pagination, and language for localized results. Example: query="Breaking Bad" returns the critically acclaimed drama series. Search for TV shows by title or keyword in the TMDb database
top_rated_movies
These are the critically acclaimed films with the best user ratings. Each movie includes: title, release date, overview, vote average, vote count, poster path, genre IDs, and TMDb ID. Use this when users ask for "best movies ever", "top rated films", "highest rated movies", or want quality recommendations. This list includes classics like The Shawshank Redemption, The Godfather, and other critically acclaimed films. Optional: page for pagination and language for localized results. Get a list of the highest-rated movies of all time on TMDb
top_rated_tv
These are the most critically acclaimed series with the best user ratings. Each TV show includes: name, first air date, overview, vote average, vote count, poster path, number of seasons and episodes, and TMDb ID. Use this when users ask for "best TV shows ever", "top rated series", or want quality TV recommendations. This list includes acclaimed series like Breaking Bad, Band of Brothers, Chernobyl, and other top-rated shows. Optional: page for pagination and language for localized results. Get a list of the highest-rated TV shows of all time on TMDb
trending
The mediaType parameter can be: "movie", "tv", "person", or "all" (returns mixed results with media_type field). The timeWindow parameter can be: "day" (trending today) or "week" (trending this week). Each result includes: title/name, overview, poster path, vote average, popularity score, and media type. Use this when users ask "what is trending?", "what is popular today?", or want to see what is currently hot in entertainment. The trending algorithm considers user activity, page views, and search patterns on TMDb. Get trending content (movies, TV shows, or people) on TMDb for today or this week
Example Prompts for The Movie Database (TMDb) in Claude Code
Ready-to-use prompts you can give your Claude Code agent to start working with The Movie Database (TMDb) immediately.
"What movies are trending today?"
"Search for movies directed by Christopher Nolan with rating above 8."
"Who starred in The Matrix and what other movies have they been in?"
Troubleshooting The Movie Database (TMDb) MCP Server with Claude Code
Common issues when connecting The Movie Database (TMDb) to Claude Code through the Vinkius, and how to resolve them.
Command not found: claude
npm install -g @anthropic-ai/claude-codeConnection timeout
The Movie Database (TMDb) + Claude Code FAQ
Common questions about integrating The Movie Database (TMDb) MCP Server with Claude Code.
How do I add an MCP server to Claude Code?
claude mcp add --transport http "" in your terminal. Claude Code registers the server and discovers all tools immediately.Can Claude Code run MCP tools in headless mode?
How do I list all connected MCP servers?
claude mcp in your terminal to see all registered servers and their status, or type /mcp inside an active Claude Code session.Connect The Movie Database (TMDb) with your favorite client
Step-by-step setup guides for every MCP-compatible client and framework:
Anthropic's native desktop app for Claude with built-in MCP support.
AI-first code editor with integrated LLM-powered coding assistance.
GitHub Copilot in VS Code with Agent mode and MCP support.
Purpose-built IDE for agentic AI coding workflows.
Autonomous AI coding agent that runs inside VS Code.
Anthropic's agentic CLI for terminal-first development.
Python SDK for building production-grade OpenAI agent workflows.
Google's framework for building production AI agents.
Type-safe agent development for Python with first-class MCP support.
TypeScript toolkit for building AI-powered web applications.
TypeScript-native agent framework for modern web stacks.
Python framework for orchestrating collaborative AI agent crews.
Leading Python framework for composable LLM applications.
Data-aware AI agent framework for structured and unstructured sources.
Microsoft's framework for multi-agent collaborative conversations.
Connect The Movie Database (TMDb) to Claude Code
Get your token, paste the configuration, and start using 15 tools in under 2 minutes. No API key management needed.