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

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:

Creating an account at TMDB
Going to your account settings
Selecting the "API" section
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.

Related MCP server: mcp-dbs

Prerequisites

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

Installation

Clone the repository:

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

Install dependencies:

pnpm install

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:

Open Claude Desktop
Go to Settings > MCP Configuration
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

MCP TMDB

MCP TMDB

About TMDB

API Overview

Rate Limits

Prerequisites

Installation

Available Tools

1. two_actors_on_screen

2. two_people

3. two_movies

4. filmography_actor_genre

5. filmography_crew_genre

6. jobs_list

Usage

Project Structure

Main Dependencies

MCP Configuration

Claude Desktop

Tool Output Examples

1. two_actors_on_screen

2. two_people

3. two_movies

4. filmography_actor_genre

4. filmography_crew_genre

5. jobs_list

Demos

two_actors_on_screen

two_movies

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API