MCP Tmdb

🚀 MCP TMDB

This project implements the Model Context Protocol (MCP) and offers tools to interact with The Movie Database (TMDB), enabling access to rich movie and TV show data.

🚀 Quick Start

This project provides a set of tools to interact with The Movie Database (TMDB) through the Model Context Protocol (MCP). Before you start, make sure you have the necessary prerequisites installed and obtain your TMDB API key.

✨ Features

• Comprehensive TMDB Interaction: Access a wide range of movie and TV show data through the TMDB API.
• Diverse Search Tools: Includes multiple search tools such as finding movies with two actors on screen, movies where two people work together, and people who worked in two films.
• Genre - Specific Filmography: Search for an actor's or crew member's filmography in a specific genre.

📦 Installation

Prerequisites

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

Steps

1. Clone the repository:

git clone https://github.com/leonardogilrodriguez/mcp-tmdb.git
cd mcp-tmdb

2. Install dependencies:

pnpm install

3. Create a .env file in the project root with your TMDB API key:

TMDB_API_KEY=your_api_key_here

💻 Usage Examples

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.

Running the Server

To run the MCP server:

pnpm inspector

To run in debug mode:

pnpm dev:debug

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
    }
]

5. 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"
        ]
    }
]

6. 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"
  ]
}

📚 Documentation

About TMDB

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.

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

🎥 Demos

two_actors_on_screen

two_movies

📄 License

This project is licensed under the MIT license.