TMDB

•
5
•

Integrates with The Movie Database (TMDB) to provide structured access to film and TV show data via the Model Context Protocol.

Leveraging the Model Context Protocol (MCP), this project offers a set of specialized tools for interacting with The Movie Database (TMDB). It simplifies complex queries, enabling users to efficiently retrieve information such as shared filmographies between actors or crew members, identify common collaborators across different movies, and filter filmographies by genre or job role. Designed for seamless integration, particularly with AI agents like Claude Desktop, it provides a structured and programmatic interface to TMDB's extensive entertainment database.

주요 기능

01Filter an actor's filmography by a given genre.
02Discover shared filmography between two specified actors.
03Identify collaborative projects between any two film professionals (cast or crew).
04Find common cast and crew members across two specific movies.
051 GitHub stars
06Filter a crew member's filmography by job and genre.

사용 사례

01Researching professional connections and collaborative histories within the film industry.
02Enhancing AI agents with structured and queryable movie/TV show data.
03Building applications that require detailed filtering and cross-referencing of entertainment data.

MCP TMDB

This project is an implementation of the Model Context Protocol (MCP) that provides tools to interact with The Movie Database (TMDB).

About TMDB

TMDB logo

The Movie Database (TMDB) is a popular, user editable database for movies and TV shows. It provides a comprehensive API that allows developers to access movie and TV show data, including:

  • Movie and TV show information
  • Cast and crew details
  • Images and posters
  • Ratings and reviews
  • Similar content recommendations
  • And much more

API Overview

The TMDB API is free to use but requires an API key. You can get your API key by:

  1. Creating an account at TMDB
  2. Going to your account settings
  3. Selecting the "API" section
  4. Requesting an API key

Rate Limits

The API has the following rate limits:

  • 40 requests per 10 seconds
  • 1000 requests per day

For more information about the API, visit the TMDB API Documentation.

Prerequisites

  • Node.js (recommended version: 18 or higher)
  • pnpm (version 10.7.0 or higher)

Installation

  1. Clone the repository:
git clone https://github.com/leonardogilrodriguez/mcp-tmdb.git
cd mcp-tmdb
  1. Install dependencies:
pnpm install
  1. Create a .env file in the project root with your TMDB API key:
TMDB_API_KEY=your_api_key_here

Available Tools

1. two_actors_on_screen

Searches for movies where two actors appear together on screen.

Parameters:

  • actor1: Name of the first actor
  • actor2: Name of the second actor
  • language: (Optional) Results language (default: "en")

2. two_people

Searches for movies where two people work together in any role.

Parameters:

  • person1: Name of the first person
  • job1: Job of the first person. Possible values: cast, crew
  • person2: Name of the second person
  • job2: Job of the second person. Possible values: cast, crew
  • language: (Optional) Results language (default: "en")

3. two_movies

Searches for people who worked in two films in any role.

Parameters:

  • movie1: Name of the first movie
  • year1: (Optional) Year of the first movie
  • movie2: Name of the second movie
  • year2: (Optional) Year of the second movie
  • language: (Optional) Results language (default: "en")

4. filmography_actor_genre

Searches for a person's filmography as an actor in a specific genre.

Parameters:

  • person: Actor's name
  • genre: (Optional) Genre name
  • language: (Optional) Results language (default: "en")

5. filmography_crew_genre

Searches for a person's filmography as a crew member in a specific genre.

Parameters:

  • person: Person's name
  • job: (Optional) Job name
  • genre: (Optional) Genre name
  • language: (Optional) Results language (default: "en")

6. jobs_list

Provides a list of available jobs to use in the filmography_crew_genre tool.

Usage

To run the MCP server:

pnpm inspector

To run in debug mode:

pnpm dev:debug

Project Structure

mcp-tmdb/
├── API/              # API functions and utilities
├── interfaces/       # Type and interface definitions
├── tools/           # Tool implementations
├── main.ts          # Main entry point
├── package.json     # Project configuration
└── .env            # Environment variables (create)

Main Dependencies

  • @modelcontextprotocol/sdk: ^1.12.1
  • dotenv: ^16.5.0
  • zod: ^3.25.55

MCP Configuration

Claude Desktop

To configure this MCP in Claude Desktop:

  1. Open Claude Desktop
  2. Go to Settings > MCP Configuration
  3. Add a new MCP with the following settings:
    "tmdb": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "tsx",
      "args": [
        "complete_path_to_mcp-tmdb\\main.ts"
      ],
      "env": {
        "TMDB_API_KEY": "your_api_key_here"
      }
    }

Tool Output Examples

1. two_actors_on_screen

Example output when searching for movies with Cary Grant and Katharine Hepburn:

[
    {
        "id": 31866,
        "title": "Sylvia Scarlett",
        "year": 1935,
        "media_type": "movie"
    },
    {
        "id": 900,
        "title": "Bringing Up Baby",
        "year": 1938,
        "media_type": "movie"
    },
    {
        "id": 16274,
        "title": "Holiday",
        "year": 1938,
        "media_type": "movie"
    },
    {
        "id": 981,
        "title": "The Philadelphia Story",
        "year": 1940,
        "media_type": "movie"
    }
]

2. two_people

Example output when searching for collaborations between Christopher Nolan and Hans Zimmer:

[	
    {
        "id": 272,
        "title": "Batman Begins",
        "year": 2005,
        "media_type": "movie"
    },
    {
        "id": 155,
        "title": "The Dark Knight",
        "year": 2008,
        "media_type": "movie"
    },
    {
        "id": 27205,
        "title": "Inception",
        "year": 2010,
        "media_type": "movie"
    }
 	...
]

3. two_movies

Example output when searching for people who worked in two movies: Titanic and The Lord of the Rings: The Return of the King:

[{
        "id": 1369,
        "name": "Bernard Hill",
        "known_for_department": "Acting"
    },
    {
        "id": 1327030,
        "name": "Lora Hirschberg",
        "job": "Sound Re-Recording Mixer",
        "known_for_department": "Sound"
    },
    {
        "id": 900,
        "name": "Christopher Boyes",
        "job": "Sound Re-Recording Mixer",
        "known_for_department": "Sound"
    },
    {
        "id": 1378696,
        "name": "Ethan Van der Ryn",
        "job": "Sound Effects Editor",
        "known_for_department": "Sound"
    },
    {
        "id": 1425978,
        "name": "Gary Summers",
        "job": "Sound Re-Recording Mixer",
        "known_for_department": "Sound"
    }
]

4. filmography_actor_genre

Example output when searching for Tom Hanks' horror movies:

[{
        "title": "He Knows You're Alone",
        "character": "Elliot",
        "media_type": "movie",
        "year": 1980
    },
    {
        "title": "The 'Burbs",
        "character": "Ray Peterson",
        "media_type": "movie",
        "year": 1989
    },
    {
        "title": "Vault of Horror I",
        "character": "Baxter",
        "media_type": "movie",
        "year": 1994
    }
]

4. filmography_crew_genre

Example output when searching for Steven Spielberg's comedy movies as director:

[{
        "title": "The Sugarland Express",
        "media_type": "movie",
        "year": 1974,
        "jobs": [
            "Director"
        ]
    },
    {
        "title": "1941",
        "media_type": "movie",
        "year": 1979,
        "jobs": [
            "Director"
        ]
    },
    {
        "title": "Amazing Stories",
        "media_type": "tv",
        "year": 1985,
        "jobs": [
            "Director"
        ]
    },
    {
        "title": "Hook",
        "media_type": "movie",
        "year": 1991,
        "jobs": [
            "Director"
        ]
    },
    {
        "title": "The Terminal",
        "media_type": "movie",
        "year": 2004,
        "jobs": [
            "Director"
        ]
    }
]

5. jobs_list

Example output of available jobs:

{
  "jobs": [
    "Director",
    "Producer",
    "Screenplay",
    "Director of Photography",
    "Editor",
    "Production Design",
    "Art Direction",
    "Set Decoration",
    "Costume Design",
    "Makeup",
    "Sound",
    "Visual Effects",
    "Original Music Composer"
  ]
}

Demos

two_actors_on_screen

Two Actors on screen

two_movies

Two Actors on screen

License

MIT