README.md•8.12 kB
# 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%"></img>
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](https://www.themoviedb.org/)
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](https://developers.themoviedb.org/3).
## Prerequisites
- Node.js (recommended version: 18 or higher)
- pnpm (version 10.7.0 or higher)
## Installation
1. Clone the repository:
```bash
git clone https://github.com/leonardogilrodriguez/mcp-tmdb.git
cd mcp-tmdb
```
2. Install dependencies:
```bash
pnpm install
```
3. 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:
```bash
pnpm inspector
```
To run in debug mode:
```bash
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:
```json
"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:
```json
[
{
"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:
```json
[
{
"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:
```json
[{
"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:
```json
[{
"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:
```json
[{
"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:
```json
{
"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
[](https://www.youtube.com/watch?v=oQ_wfArl2cw)
### two_movies
[](https://www.youtube.com/watch?v=E9buDNeFVBo)
## License
MIT