Supports environment variable management for storing and accessing the TMDB API key securely within the MCP server configuration.
Serves as the runtime environment for executing the MCP server.
Used as the package manager for installing and managing the MCP server dependencies.
Provides tools for interacting with The Movie Database (TMDB) API, enabling queries for movies where actors appear together, finding collaborations between people in different roles, identifying people who worked on specific films, and retrieving filmographies filtered by genre and job role.
Implements data validation for the parameters and responses when interacting with the TMDB API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP TMDBfind movies where Tom Hanks and Meg Ryan appear together"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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-tmdbInstall dependencies:
pnpm installCreate a
.envfile in the project root with your TMDB API key:
TMDB_API_KEY=your_api_key_hereAvailable 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 inspectorTo run in debug mode:
pnpm dev:debugProject 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