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
<img src=https://www.themoviedb.org/assets/2/v4/logos/v2/blue_short-8e7b30f73a4020692ccca9c88bafe5dcb6f8a62a4c6bc55cd9ba82bb2cd95f6c.svg alt="TMDB logo" width="100%">
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.
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
.envfile 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 actoractor2: Name of the second actorlanguage: (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 personjob1: Job of the first person. Possible values: cast, crewperson2: Name of the second personjob2: Job of the second person. Possible values: cast, crewlanguage: (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 movieyear1: (Optional) Year of the first moviemovie2: Name of the second movieyear2: (Optional) Year of the second movielanguage: (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 namegenre: (Optional) Genre namelanguage: (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 namejob: (Optional) Job namegenre: (Optional) Genre namelanguage: (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_movies
License
MIT