Connect The Movie Database (TMDB) to Claude: Explore Cast & Film Data

If your team uses ChatGPT, check out our guide on connecting The Movie Database (TMDB) to ChatGPT or explore our broader architectural overview on connecting The Movie Database (TMDB) to AI Agents.

The Movie Database (TMDB) is the de facto metadata backbone for thousands of media applications, streaming platforms, and analytical tools. Giving a Large Language Model (LLM) like Claude direct, structured access to TMDB allows you to automate content curation, analyze cast and crew data, and build conversational recommendation engines. But giving an AI agent reliable API access requires a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and TMDB's REST architecture.

You can either spend weeks building, hosting, and maintaining this translation layer yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for TMDB, connect it natively to Claude, and execute complex media research workflows using natural language.

The Engineering Reality of the TMDB API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, implementing it against TMDB's specific API surface is an engineering headache. You are not just integrating a simple REST API - you are integrating an interconnected graph of movies, TV shows, seasons, episodes, and people, all heavily reliant on unique schema patterns.

If you decide to build a custom MCP server for TMDB, you own the entire API lifecycle. Here are the specific architectural challenges you will face:

The Image Path Resolution Problem Unlike most modern APIs, TMDB does not return fully qualified URLs for media assets like posters, backdrops, and actor profiles. Instead, endpoints return raw file paths (e.g., "poster_path": "/kqjL17yufvn9OVLyXYpvtyrFfak.jpg"). To render or process these images, clients must first query the /configuration endpoint to retrieve the secure_base_url and a list of valid image sizes, then manually concatenate the strings. If you expose raw TMDB paths directly to Claude, the LLM will inevitably hallucinate a base URL (often guessing tmdb.org/images/ or similar). A properly managed MCP server handles this by retrieving configuration data alongside media data, ensuring the LLM has the exact context it needs without requiring multi-step translation logic in the prompt.

Bifurcated Authentication States TMDB uses two entirely different authentication models depending on the operation. Read-only metadata queries simply require a Bearer token or API key. However, user-specific write operations - like rating a movie or adding a show to a watchlist - require a complex three-step session creation flow. You must generate a request token, have the user validate it via a login screen, and then exchange it for a session_id. Managing these divergent authentication lifecycles inside a stateless MCP server requires significant session management boilerplate. A managed integration layer abstracts this entirely, passing the correct credential format based on the requested endpoint.

Rate Limits and 429 Handling TMDB enforces a rate limit of 50 requests per second. While generous for standard apps, AI agents executing recursive loops - like "Find the top 10 movies from 1999, then fetch the full cast for each, then get the biography for every lead actor" - can easily trigger rate limits. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the TMDB API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller (your LLM framework or Claude Desktop) is responsible for intercepting these headers and managing retry and backoff logic.

How to Generate a TMDB MCP Server with Truto

Truto dynamically generates MCP servers based on the endpoints you have enabled and documented for TMDB. Because tool generation is documentation-driven, endpoints only become tools if they have an associated JSON Schema and description. This acts as a quality gate, preventing your LLM from drowning in undocumented endpoints.

There are two ways to create your TMDB MCP server in Truto.

Method 1: Via the Truto UI

1. Log into your Truto dashboard and navigate to the integrated account page for your TMDB connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure the server. You can optionally restrict the server to specific methods (e.g., read only) or specific tags.
5. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the API

For teams building automated provisioning pipelines, you can generate an MCP server programmatically. The API validates that the TMDB integration is connected, creates a secure token, stores it in highly available KV storage, and returns a ready-to-use URL.

Make a POST request to the /mcp endpoint on the integrated account:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TMDB Discovery Agent",
    "config": {
      "methods": ["read"]
    }
  }'

The response contains your tokenized server URL:

{
  "id": "mcp-7a8b9c0d",
  "name": "TMDB Discovery Agent",
  "config": { "methods": ["read"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with Claude. Truto MCP servers use the standardized JSON-RPC 2.0 protocol over HTTP POST.

Connecting via the Claude UI (or ChatGPT)

If you are using a modern UI client that natively supports remote MCP connections (like ChatGPT's Custom Connectors or Claude's web interface):

1. In your AI client, navigate to Settings -> Integrations (or Settings -> Connectors -> Add custom connector).
2. Select the option to add a remote MCP server.
3. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
4. Save the configuration. The client will immediately send an initialize request to the URL, discover the TMDB tools, and make them available in your chat context.

Connecting via Claude Desktop Config File

Claude Desktop currently expects MCP servers to communicate over standard input/output (stdio) rather than HTTP by default. To bridge this gap, you use the official @modelcontextprotocol/server-sse package, which acts as a local proxy that translates Claude's stdio commands into Server-Sent Events (SSE) and HTTP requests for Truto.

Open your Claude Desktop configuration file.

• On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• On Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your TMDB MCP server to the mcpServers object:

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}

Restart Claude Desktop. The application will boot the SSE bridge, connect to Truto, and pull down the complete schemas for TMDB.

Hero Tools for TMDB

Truto automatically generates descriptive, snake_case tool names based on TMDB's resources. While the full integration supports dozens of endpoints, here are the highest-leverage tools for building media-focused AI workflows.

list_all_the_movie_database_tmdb_search_multis

This is the ultimate entry point for natural language agents. When a user asks an ambiguous question (e.g., "Find me info on The Matrix"), the agent doesn't know if they mean the movie, a TV spin-off, or a video game. This tool queries TMDB's multi-search endpoint, returning movies, TV shows, and people in a single structured array.

"I need you to look up 'Christopher Nolan' in TMDB. Find out if it matches a person or a production company, and give me their top-level IDs so we can dig deeper."

list_all_the_movie_database_tmdb_discover_movies

The discovery engine is the most powerful query tool in TMDB. It supports over 30 filters, allowing the agent to combine constraints like release years, specific genres, minimum vote averages, and specific cast members (using their person IDs).

"Find me all science fiction movies released between 1990 and 1999 that have a vote average of at least 8.0. Limit the results to English language films."

get_single_the_movie_database_tmdb_3_movie_by_id

Once an agent identifies a target movie, this tool fetches the comprehensive top-level metadata. It returns budget, revenue, runtime, release dates, status, and associated production companies.

"Get the full details for the movie with ID 155 (The Dark Knight). I need to know the exact runtime, the total revenue, and the primary production companies involved."

list_all_the_movie_database_tmdb_combined_credits

To analyze a specific actor or crew member's career trajectory, this tool returns their combined movie and TV credits. It structures the data logically, separating cast appearances (with character names) from crew roles (with department and job titles).

"Look up the combined credits for person ID 31 (Tom Hanks). I want a list of all the movies he has produced, separated from the movies where he only acted."

list_all_the_movie_database_tmdb_watch_providers

One of the most common user intents is "Where can I watch this?" This tool accepts a movie ID and returns the streaming, rental, and purchase providers available, grouped by ISO 3166-1 country codes (e.g., US, GB, AU).

"Check the watch providers for the movie Inception (ID 27205). Tell me which streaming services currently have it available for flat-rate streaming in the United States (US)."

For the complete inventory of TMDB tools, including TV season management, collection analytics, and rating endpoints, visit the TMDB integration page.

Workflows in Action

Connecting Claude to TMDB allows you to automate complex research tasks that would traditionally require humans to click through dozens of IMDB or TMDB pages. Here is how Claude executes real-world multi-step workflows.

Use Case 1: The Content Curator

A content marketing manager for a streaming blog wants to write an article about highly-rated, obscure 90s thriller movies that are currently available on Netflix US.

"Find me 5 thriller movies released in the 1990s with fewer than 1,000 vote counts but a vote average over 7.0. Then, check the watch providers for each one and tell me which ones are currently streaming on Netflix in the US."

How Claude executes this:

1. Claude calls list_all_the_movie_database_tmdb_discover_movies, passing query parameters for with_genres (thriller ID), release_date.gte (1990-01-01), release_date.lte (1999-12-31), vote_count.lte (1000), and vote_average.gte (7.0).
2. TMDB returns a list of matching movie IDs.
3. Claude loops through the top 5 movie IDs, calling list_all_the_movie_database_tmdb_watch_providers for each one.
4. Claude filters the provider responses to look specifically for the "US" region and the provider name "Netflix" under the flatrate array.
5. Claude synthesizes the final list and outputs a structured response for the user, detailing the plot summaries and verifying streaming availability.

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant TMDB as TMDB API
    
    User->>Claude: "Find 90s hidden gem thrillers on Netflix US"
    Claude->>MCP: list_all_the_movie_database_tmdb_discover_movies<br>{"with_genres": "53", "primary_release_date.gte": "1990-01-01"}
    MCP->>TMDB: GET /3/discover/movie
    TMDB-->>MCP: JSON Movie Results
    MCP-->>Claude: Filtered Movie IDs
    
    loop For Top 5 Movies
        Claude->>MCP: list_all_the_movie_database_tmdb_watch_providers<br>{"movie_id": 12345}
        MCP->>TMDB: GET /3/movie/12345/watch/providers
        TMDB-->>MCP: Provider JSON
        MCP-->>Claude: Regional Streaming Data
    end
    
    Claude-->>User: Formatted list of Netflix-available movies

Use Case 2: The Entertainment Analyst

A data journalist wants to analyze the overlap between two prominent actors to build a "six degrees of separation" visualization.

"Find all the movies where both Leonardo DiCaprio and Brad Pitt appeared in the cast together. For each movie, tell me the box office revenue and the character names they played."

How Claude executes this:

1. Claude calls list_all_the_movie_database_tmdb_search_people twice - once for "Leonardo DiCaprio" and once for "Brad Pitt" - to retrieve their exact TMDB person IDs.
2. Claude calls list_all_the_movie_database_tmdb_discover_movies and uses the with_cast parameter, supplying a comma-separated string of both person IDs to force an intersection.
3. For each movie ID returned by the discovery query, Claude calls get_single_the_movie_database_tmdb_3_movie_by_id to extract the revenue field.
4. Claude then calls list_all_the_movie_database_tmdb_credits for each movie to map the specific character names to the respective actors.
5. The agent formats the financial data and character lists into a clean report.

Security and Access Control

Exposing a sprawling graph API like TMDB to an LLM requires strict governance. If you give an agent access to user-authenticated endpoints, it could theoretically delete watchlists or spam ratings. Truto allows you to lock down MCP servers using cryptographic tokens and specific configurations:

• Method Filtering: By defining methods: ["read"] during server creation, you completely strip all POST, PUT, PATCH, and DELETE tools from the MCP server. The LLM simply cannot see or execute write operations.
• Tag Filtering: You can restrict the MCP server to specific resource domains. For example, setting tags: ["movies", "tv"] ensures the agent cannot query the people or companies endpoints.
• Expiration Controls: Using the expires_at property, you can generate temporary MCP servers for contractors, automated CI/CD runs, or ephemeral chat sessions. Once the ISO timestamp passes, the server self-destructs and associated state is purged.
• Secondary Authentication: By enabling require_api_token_auth: true, the URL alone is no longer sufficient. The MCP client must also pass a valid Truto API token in the Authorization header, preventing lateral movement if the URL is leaked in a log file.

Build Media Workflows That Actually Scale

LLMs are incredibly adept at parsing media metadata, synthesizing plot points, and building complex cross-referencing queries. But forcing your engineering team to build custom JSON schemas, handle rate limit passthroughs, and map complex ID-based relationships for TMDB is a waste of resources.

By routing Claude through Truto's managed MCP server, you instantly convert TMDB's massive graph into standardized, AI-ready tools. You define the access rules, Claude handles the reasoning, and Truto manages the protocol.