Imdb MCP Server

🚀 IMDb MCP Server Usage Guide

This guide provides a detailed introduction to the installation, configuration, and usage of the IMDb MCP server, along with technical details and precautions.

🚀 Quick Start

📦 Installation

1. Run the Server Using MCP CLI

# Run directly
python imdb_server.py

# Or use MCP CLI
mcp run imdb_server.py

# If using Docker, the server will start automatically with the container
docker run -d -p 8000:8000 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

2. Configure Environment Variables

Set the following environment variables in the terminal:

# Set the IMDb API key
export RAPID_API_KEY_IMDB=your_api_key_here

# If using Docker, you can pass the parameter when starting the container
docker run -d -p 8000:8000 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

3. Configure claude_desktop_config.json

Add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "imdb_server": {
      "command": "/path/to/your/python",
      "args": [
        "/path/to/imdb_server.py"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

💻 Usage Examples

1. Data Retrieval Tools

All data retrieval tools support pagination, returning a maximum of 5 results per page.

Example: Get the Top 250 Movies

# Get the top 5
get_top_250_movies()

# Get the 6th to 10th
get_top_250_movies(start=5)

2. Pagination System

Request Example:

get_top_250_movies(start=5) # Returns items 6 - 10

Response Example:

{
  "movies": [
    {
      "id": "tt0012345",
      "title": "Movie Title",
      "year": 2023,
      "rating": 9.5,
      "description": "Movie description"
    },
    ...
  ],
  "metadata": {
    "totalCount": 250,
    "hasMore": true,
    "nextStart": 10
  }
}

🔧 Technical Details

Implementation Framework

• IMDb API: Accessed via RapidAPI.
• MCP: Used for API interfaces.
• Requests: Used for API communication.
• FastMCP: Server implementation framework.
• Custom Cache System: In-memory cache.
• Pagination System: Limits the number of results returned per page to 5.

Cache Mechanism

• Default Cache Configuration:

  response_cache = ResponseCache(expiry_seconds=120, max_size=50)
  

• Features:
  • Caches responses in memory.
  • Sets an expiration time (default: 10 minutes).
  • Defines a maximum cache size (default: 100 keys).
  • Regularly cleans up expired entries.

⚠️ Important Note

• API call limits are subject to your RapidAPI plan.
• Some detailed information requires separate requests.
• Pagination needs to be implemented manually.
• The cache mechanism can improve performance, but cache invalidation needs to be handled.

📚 Appendix

Install Dependencies

pip install requests mcp

Example Code

from imdb_mcp import IMDBClient

client = IMDBClient('your_api_key_here')
movies = client.get_top_250_movies(start=0)
print(movies)

By following the above steps, you can successfully configure and use the IMDb MCP server.