Skip to main content
Glama
Sign In
enesjakozh

imdb-mcp-server

by uzaysozen
Verified
GitHub
Python
MIT License
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Offers Docker deployment support with a pre-configured Docker image, allowing containerized execution of the IMDb MCP server with proper environment variable configuration.

  • Provides comprehensive access to IMDb movie and TV show data, including search capabilities, detailed information about titles, cast and crew details, top-rated content lists, box office data, upcoming releases, and country-specific movie information with special focus on Indian cinema.

  • Utilizes RapidAPI's IMDb API service to fetch movie and TV show information, requiring users to set up a RapidAPI account and subscribe to the IMDb API to obtain the necessary API key.

IMDb MCP Server

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

Table of Contents

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

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. Set the environment variable:
    RAPID_API_KEY_IMDB=your_api_key_here

Tools

Search Tools

ToolDescriptionExample
search_imdbSearch for movies and TV shows with various filtering optionssearch_imdb(primary_title="Inception")

IMDb ID Tools

ToolDescriptionExample
get_imdb_detailsRetrieve detailed information about a movie or TV showget_imdb_details(imdb_id="tt1375666")
get_directorsRetrieve the directors of a movieget_directors(imdb_id="tt1375666")
get_castRetrieve the cast of a movieget_cast(imdb_id="tt1375666")
get_writersRetrieve the writers of a movieget_writers(imdb_id="tt1375666")

Configuration Tools

ToolDescriptionExample
get_typesGet all available content typesget_types()
get_genresGet all available genresget_genres()
get_countriesGet all available countriesget_countries()
get_languagesGet all available languagesget_languages()

Movies Tools

Paginated (5 results per page)

ToolDescriptionExample
get_top_250_moviesGet the top 250 movies from IMDbget_top_250_movies()
get_top_box_office_usGet the US box office recordsget_top_box_office_us()
get_most_popular_moviesGet the most popular moviesget_most_popular_movies()

TV Shows Tools

Paginated (5 results per page)

ToolDescriptionExample
get_top_250_tv_showsGet the top 250 TV shows from IMDbget_top_250_tv_shows()
get_most_popular_tv_showsGet the most popular TV showsget_most_popular_tv_shows()

Upcoming Releases Tools

Paginated (5 results per page)

ToolDescriptionExample
get_upcoming_releasesGet upcoming movie and TV show releases by countryget_upcoming_releases(country_code="US", type="MOVIE")
get_available_country_codes_for_upcoming_releasesGet available country codes for upcoming releasesget_available_country_codes_for_upcoming_releases()

India Spotlight Tools (Paginated)

Paginated (5 results per page)

ToolDescriptionExample
get_top_rated_malayalam_moviesGet top 50 rated Malayalam moviesget_top_rated_malayalam_movies()
get_upcoming_indian_moviesGet most anticipated upcoming Indian moviesget_upcoming_indian_movies()
get_trending_tamil_moviesGet trending Tamil moviesget_trending_tamil_movies()
get_trending_telugu_moviesGet trending Telugu moviesget_trending_telugu_movies()
get_top_rated_tamil_moviesGet top 50 rated Tamil moviesget_top_rated_tamil_movies()
get_top_rated_telugu_moviesGet top 50 rated Telugu moviesget_top_rated_telugu_movies()
get_top_rated_indian_moviesGet top 250 rated Indian moviesget_top_rated_indian_movies()

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

To install IMDb Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @uzaysozen/imdb-mcp-server --client claude
  1. Clone this repository
git clone https://github.com/uzaysozen/imdb-mcp-server.git cd imdb-mcp-server
  1. Install dependencies
pip install -r requirements.txt
  1. Build the Docker image
docker build -t imdb_server .
  1. Run the Docker container (ensure your API key is passed as an environment variable)
docker run -d -p 8000:8000 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server
  1. Add this to your claude_desktop_config.json:
{ "mcpServers": { "imdb_server": { "command": "docker", "args": [ "exec", "-i", "imdb_server", "imdb-mcp-server" ], "env": { "RAPID_API_KEY_IMDB": "your_api_key_here" } } } }

Option 2: Direct Python Execution

  1. Clone this repository
git clone https://github.com/uzaysozen/imdb-mcp-server.git cd imdb-mcp-server
  1. Install dependencies
pip install -r requirements.txt
  1. Set the API key environment variable
export RAPID_API_KEY_IMDB=your_api_key_here
  1. Add this to your claude_desktop_config.json, adjusting the Python path as needed:
{ "mcpServers": { "imdb_server": { "command": "/path/to/your/python", "args": [ "/path/to/imdb_server.py" ], "env": { "RAPID_API_KEY_IMDB": "your_api_key_here" } } } }

Starting the Server

# Start the server directly python imdb_server.py # Or using MCP CLI mcp run imdb_server.py # Or if using Docker, the server starts automatically with the container docker run -d -p 8000:8000 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

After adding your chosen configuration, restart Claude Desktop to load the IMDb server. You'll then be able to use all the movie and TV show data tools in your conversations with Claude.

Technical Details

The server is built on:

  • IMDb API via RapidAPI
  • MCP for API interface
  • Requests for API communication
  • FastMCP for server implementation
  • Custom in-memory caching system
  • Smart pagination that limits results to 5 items per request, optimizing for AI agent consumption

Pagination System

All data retrieval tools implement pagination to enhance AI agent performance:

Purpose

  • AI-Optimized Responses: Limits each response to 5 items, preventing overwhelm in AI agents that process the data
  • Focused Results: Helps agents provide more relevant and concise information to users
  • Improved Processing: Reduces the cognitive load on AI agents when analyzing movie and TV show data

Implementation

  • Each paginated endpoint accepts a start parameter (default: 0)
  • Results include navigation metadata (totalCount, hasMore, nextStart)
  • Consistent 5-item page size across all collection endpoints
  • Example request with pagination: get_top_250_movies(start=5) returns items 6-10

Benefits

  • Better Agent Responses: Prevents AI agents from receiving too much data at once
  • Manageable Information: Creates digestible chunks of data that agents can process effectively
  • Sequential Access: Allows structured exploration of large datasets through multiple tool calls

Caching System

The server implements an efficient caching system to improve performance and reduce API calls:

Features

  • In-memory Cache: Stores API responses in memory for quick retrieval
  • Configurable Expiration and Size: Cache entries expire after a customizable time period (default: 10 minutes) and have a default size of 100 cache keys
  • Automatic Cache Cleaning: Periodically (default: 5 minutes) removes expired entries to manage memory usage using a background thread
  • Cache Keys: Generated based on the URL and query parameters to ensure uniqueness

Benefits

  • Reduced API Usage: Helps stay within API rate limits by reusing responses
  • Faster Response Times: Eliminates network latency for cached queries
  • Cost Efficiency: Minimizes the number of API calls, especially for popular or repeated queries

Configuration

The cache size and expiration time can be adjusted in the code:

# Default are 600 seconds (10 minutes) and 100 cache keys response_cache = ResponseCache(expiry_seconds=120, max_size=50)

Limitations

  • API rate limits apply based on your RapidAPI subscription
  • Some detailed information may require additional API calls
  • Search results may be limited to a certain number of items per request
  • In-memory cache is lost when server restarts
  • All paginated responses return a maximum of 5 items per page

Troubleshooting

ProblemSolution
API key not recognizedEnsure the RAPID_API_KEY_IMDB environment variable is properly set
Rate limit exceededCheck your RapidAPI subscription tier and limits
Timeout errorsThe server has a 30-second timeout; for large requests, try limiting parameters
Empty resultsTry broader search terms or check if the content exists in IMDb's database
High memory usageIf running for extended periods with many unique queries, restart the server occasionally to clear the cache

License

This MCP server is available under the MIT License.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

A comprehensive MCP server providing detailed IMDb data including movies, TV shows, and upcoming releases.

  1. Table of Contents
    1. Overview
      1. Features
        1. Configuration
          1. Tools
            1. Search Tools
            2. IMDb ID Tools
            3. Configuration Tools
            4. Movies Tools
            5. TV Shows Tools
            6. Upcoming Releases Tools
            7. India Spotlight Tools (Paginated)
          2. Example Prompt and Response
            1. Installation
              1. Installing via Smithery
              2. Option 1: Using Docker (Recommended)
              3. Option 2: Direct Python Execution
            2. Starting the Server
              1. Technical Details
                1. Pagination System
                2. Caching System
              2. Limitations
                1. Troubleshooting
                  1. License

                    Appeared in Searches

                    ID: 420kawzfbk