TMDB MCP Server

A Model Context Protocol (MCP) server that allows LLMs to search for movies and TV shows using the The Movie Database (TMDB) API.

Features

• Search Movies: Find movies by title with support for region and language.
• Search TV Shows: Find TV shows by title with language support.
• Get Details: Retrieve detailed metadata for movies and TV shows (runtime, budget, seasons, etc.).
• Trending: Discover today's or this week's trending movies and TV shows.
• Search People: Search for actors, directors, and other crew members.
• Direct Links: Provides TMDb URLs for easy access to more details.

Prerequisites

• Node.js (v18 or higher)
• A TMDB API Key. You can get one by creating an account on themoviedb.org and applying for an API key in your account settings.

Configuration

MCP Client Configuration (e.g., Claude Desktop)

To use this server with Claude Desktop, add it to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["-y", "@lonzzi/tmdb-mcp-server"],
      "env": {
        "TMDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

All tools support an optional language argument (e.g., en-US, zh-CN, fr-FR) to get localized results. Default is en-US.

search_movies

Search for movies on TMDB by title.

• Arguments:
  • query (string, required): The movie title to search for.
  • language (string, optional): Language code (default: en-US).
  • region (string, optional): ISO 3166-1 code to filter release dates (e.g., US, KR).

search_tv_shows

Search for TV shows on TMDB by title.

• Arguments:
  • query (string, required): The TV show title to search for.
  • language (string, optional): Language code (default: en-US).

get_movie_details

Get detailed information about a specific movie.

• Arguments:
  • movieId (number, required): The TMDB ID of the movie.
  • language (string, optional): Language code (default: en-US).

get_tv_show_details

Get detailed information about a specific TV show.

• Arguments:
  • tvShowId (number, required): The TMDB ID of the TV show.
  • language (string, optional): Language code (default: en-US).

get_trending_movies

Get the daily or weekly trending movies.

• Arguments:
  • timeWindow (string, optional): day or week (default: week).
  • language (string, optional): Language code (default: en-US).

get_trending_tv

Get the daily or weekly trending TV shows.

• Arguments:
  • timeWindow (string, optional): day or week (default: week).
  • language (string, optional): Language code (default: en-US).

search_person

Search for people (actors, directors, etc.).

• Arguments:
  • query (string, required): The name to search for.
  • language (string, optional): Language code (default: en-US).

Development

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Create a .env file with your TMDB_API_KEY.

4. Build the project:

   npm run build
   

Running Tests

npm test