IMDb MCP Server

Verified on MCP Review

A Python server implementing Model Context Protocol (MCP) for movie and TV show information using the IMDb API service.

Table of Contents

- Overview - Features - Requirements - Configuration - Tools - Search Tools - IMDb ID Tools - Configuration Tools - Movies Tools - TV Shows Tools - Upcoming Releases Tools - India Spotlight Tools - Example Prompt and Response - Installation - Starting the Server - Technical Details - Transport Modes - Pagination System - Caching System - Limitations - Troubleshooting - License

Overview

This server provides a comprehensive set of tools for accessing IMDb data through the IMDb API. It serves as a bridge between agents and the IMDb database, offering detailed information about movies, TV shows, actors, directors, and more.

Features

- 🎬 Movie and TV show search capabilities
- 📋 Detailed information about movies and TV shows
- 👨‍👩‍👧‍👦 Cast and crew information
- 🏆 Top-rated and popular content lists
- 💰 Box office data
- 🌍 Country-specific movie information (with special focus on Indian cinema)
- 🔜 Upcoming releases
- 🔄 Efficient response caching system

Requirements

- Python: 3.13 or higher
- Package Manager: uv (recommended) or pip
- RapidAPI Account: Required for IMDb API access

Configuration

This server requires an API key from RapidAPI for the IMDb API service:

1. Create an account on RapidAPI
2. Subscribe to the IMDb API on RapidAPI
3. Configure the API key using one of these methods:

Method 1: Smithery Configuration (for HTTP mode)
- When installing via Smithery, provide your API key through the Smithery configuration system
- The key is passed per-request, allowing for multi-user scenarios

Method 2: Environment Variable (for stdio mode)

   export RAPID_API_KEY_IMDB=your_api_key_here

   

Tools

Search Tools

| Tool | Description | Example |
|------|-------------|---------|
| search_imdb | Search for movies and TV shows with various filtering options | search_imdb(primary_title="Inception") |

IMDb ID Tools

| Tool | Description | Example |
|------|-------------|---------|
| get_imdb_details | Retrieve detailed information about a movie or TV show | get_imdb_details(imdb_id="tt1375666") |
| get_directors | Retrieve the directors of a movie | get_directors(imdb_id="tt1375666") |
| get_cast | Retrieve the cast of a movie | get_cast(imdb_id="tt1375666") |
| get_writers | Retrieve the writers of a movie | get_writers(imdb_id="tt1375666") |

Configuration Tools

| Tool | Description | Example |
|------|-------------|---------|
| get_types | Get all available content types | get_types() |
| get_genres | Get all available genres | get_genres() |
| get_countries | Get all available countries | get_countries() |
| get_languages | Get all available languages | get_languages() |

Movies Tools

Paginated (5 results per page)

| Tool | Description | Example |
|------|-------------|---------|
| get_top_250_movies | Get the top 250 movies from IMDb | get_top_250_movies(start=0) |
| get_top_box_office_us | Get the US box office records | get_top_box_office_us(start=0) |
| get_most_popular_movies | Get the most popular movies | get_most_popular_movies(start=0) |

TV Shows Tools

Paginated (5 results per page)

| Tool | Description | Example |
|------|-------------|---------|
| get_top_250_tv_shows | Get the top 250 TV shows from IMDb | get_top_250_tv_shows(start=0) |
| get_most_popular_tv_shows | Get the most popular TV shows | get_most_popular_tv_shows(start=0) |

Upcoming Releases Tools

Paginated (5 results per page)

| Tool | Description | Example |
|------|-------------|---------|
| get_upcoming_releases | Get upcoming movie and TV show releases by country | get_upcoming_releases(country_code="US", type="MOVIE", start=0) |
| get_country_codes_for_upcoming_releases | Get available country codes for upcoming releases | get_country_codes_for_upcoming_releases() |

India Spotlight Tools

Paginated (5 results per page)

| Tool | Description | Example |
|------|-------------|---------|
| get_top_rated_malayalam_movies | Get top 50 rated Malayalam movies | get_top_rated_malayalam_movies(start=0) |
| get_upcoming_indian_movies | Get most anticipated upcoming Indian movies | get_upcoming_indian_movies(start=0) |
| get_trending_tamil_movies | Get trending Tamil movies | get_trending_tamil_movies(start=0) |
| get_trending_telugu_movies | Get trending Telugu movies | get_trending_telugu_movies(start=0) |
| get_top_rated_tamil_movies | Get top 50 rated Tamil movies | get_top_rated_tamil_movies(start=0) |
| get_top_rated_telugu_movies | Get top 50 rated Telugu movies | get_top_rated_telugu_movies(start=0) |
| get_top_rated_indian_movies | Get top 250 rated Indian movies | get_top_rated_indian_movies(start=0) |

Example Prompt and Response

What are the 5 action movies that will be released in the nearest future?

I'll find the upcoming action movies for you.

Called MCP tool ```get_upcoming_releases

Now I'll look for the action movies from these upcoming releases:

Called MCP tool 

get_upcoming_releases

Based on the search results, here are the 5 upcoming action movies that will be released in the nearest future:

1. A Minecraft Movie (April 4, 2025)

   - Genres: Action, Adventure, Comedy

   - Description: Four misfits are pulled through a portal into a cubic wonderland and embark on a quest with an expert crafter to get back home.
2. Freaky Tales (April 4, 2025)

   - Genres: Action, Adventure, Comedy

   - Description: Four interconnected stories set in 1987 Oakland, CA about the love of music, movies, people, places and memories.
3. Wake Up (April 4, 2025)

   - Genres: Action, Horror

   - Description: Young activists invade a furniture store to protest environmental issues but find themselves trapped with a hunting-obsessed night guard.
4. Warfare (April 11, 2025)

   - Genres: Action, Drama, War

   - Description: Based on ex-Navy Seal Ray Mendoza's real-life experiences during the Iraq War.
5. The Amateur (April 11, 2025)

   - Genres: Action, Thriller

   - Description: A CIA cryptographer blackmails his agency into training him to pursue terrorists who killed his wife.
Installation
Installing via Smithery (Recommended)
To install IMDb Server for Claude Desktop automatically via Smithery:

bash
npx -y @smithery/cli install @uzaysozen/imdb-mcp-server --client claude

This will automatically configure the server with your RapidAPI key through Smithery's configuration system.

Option 1: Using Docker
1. Clone this repository

bash
git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server

2. Build the Docker image

bash
docker build -t imdb_server .

3. Run the Docker container

bash
docker run -d -p 8081:8081 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

Note: The Docker container runs in HTTP mode by default on port 8081.

Option 2: Direct Python Execution (using uv)
1. Clone this repository

bash
git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server

2. Install uv (if not already installed)

bash