mikefinneran-sudo/movie-mcp-serve

Movie MCP Server

A Model Context Protocol (MCP) server that provides movie ratings and overviews using The Movie Database (TMDB) API. This server enables AI assistants to search for movies and retrieve detailed information including ratings, overviews, and cast information.

Features

• Flexible Movie Search: Search by exact title, description, or even actor names
• Rich Movie Information: Get star ratings (out of 10), plot overviews, release dates, and cast
• Natural Language Queries: Handles various query formats:
  • "What was the rating for Rounders?"
  • "What was the rating for that Matt Damon poker movie?"
  • "What was the rating for the poker movie starring Ed Norton and John Malkovich?"
• MCP Compliant: Built using the official Model Context Protocol Python SDK

Architecture

The server consists of three main components:

1. TMDBClient: Handles all API interactions with The Movie Database

   • Movie search by title/keywords
   • Detailed movie information retrieval
   • Actor search and filmography lookup

2. MovieMCPServer: MCP protocol implementation

   • Exposes the get_movie_info tool
   • Handles natural language query processing
   • Formats responses for optimal readability

3. Server Runtime: AsyncIO-based stdio server

   • Communicates via standard input/output
   • Integrates with MCP-compatible clients

Prerequisites

• Python 3.10 or higher
• A TMDB API key (free)
• pip (Python package manager)

Setup Instructions

1. Get a TMDB API Key

1. Create a free account at The Movie Database
2. Once logged in, go to API Settings
3. Request an API key (choose "Developer" if asked)
4. Copy your API key (v3 auth)

2. Clone or Extract the Project

# If you received a zip file
unzip movie-mcp-server.zip
cd movie-mcp-server

# Or if in a git repository
cd movie-mcp-server

3. Create a Virtual Environment

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

4. Install Dependencies

pip install -r requirements.txt

5. Configure Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit .env and add your TMDB API key
# On macOS/Linux:
nano .env

# On Windows:
notepad .env

Replace your_api_key_here with your actual TMDB API key:

TMDB_API_KEY=your_actual_api_key_here

6. Make the Server Executable (Optional)

chmod +x server.py

Running the Server

Standalone Mode (for testing)

You can run the server directly to verify it starts correctly:

# Load environment variables and run
source .env  # On macOS/Linux
# Or
set -a; source .env; set +a  # Alternative for bash

python server.py

The server will start and wait for MCP protocol messages on stdin.

Integration with MCP Clients

Claude Desktop Configuration

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "movie": {
      "command": "python",
      "args": ["/absolute/path/to/movie-mcp-server/server.py"],
      "env": {
        "TMDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace /absolute/path/to/movie-mcp-server with the actual path to your project directory.

Generic MCP Client

# The server communicates via stdio
python server.py

Then send MCP protocol messages via stdin.

Usage Examples

Once integrated with an MCP client (like Claude Desktop), you can ask:

Example 1: Search by Exact Title

User: What was the rating for Rounders?

Response:
**Rounders** (1998)
⭐ Rating: 7.1/10 (based on 1,234 votes)

Overview:
A young reformed gambler must return to playing big stakes poker to help a friend pay off loan sharks...

Top Cast:
Matt Damon, Edward Norton, John Malkovich, Gretchen Mol, John Turturro

Example 2: Search by Description with Actor

User: What was the rating for that Matt Damon poker movie?

Response:
**Rounders** (1998)
⭐ Rating: 7.1/10 (based on 1,234 votes)
...

Example 3: Search by Multiple Actors and Genre

User: What was the rating for the poker movie starring Ed Norton and John Malkovich?

Response:
**Rounders** (1998)
⭐ Rating: 7.1/10 (based on 1,234 votes)
...

Project Structure

movie-mcp-server/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── .env.example          # Example environment configuration
├── .gitignore           # Git ignore rules
└── README.md            # This file

Code Design Decisions

1. Asynchronous Architecture

• Uses asyncio and httpx for non-blocking I/O
• Enables efficient handling of multiple concurrent requests
• Better resource utilization when integrated into larger systems

2. Separation of Concerns

• TMDBClient: Pure API client, no MCP logic
• MovieMCPServer: MCP protocol handling, no API details
• Easy to test, modify, and extend each component independently

3. Error Handling

• Graceful degradation when movies aren't found
• Detailed logging for debugging
• User-friendly error messages

4. Search Strategy

• Primary: Direct TMDB search (handles titles and many natural language queries)
• TMDB's search is sophisticated enough to match actor names in queries
• Future enhancement: Could add NLP to extract actors and find common movies

5. Response Format

• Markdown formatting for rich text display
• Star emoji for visual appeal
• Includes alternative matches for ambiguous queries
• Formatted numbers for better readability

API Rate Limits

TMDB's free tier allows:

• 40 requests every 10 seconds per IP address
• This server makes 1-2 requests per query (search + details)
• Should be sufficient for normal AI assistant usage

Troubleshooting

"TMDB_API_KEY environment variable not set"

• Ensure your .env file exists and contains your API key
• Make sure you're in the correct directory
• Try setting the environment variable manually: export TMDB_API_KEY=your_key

"No movies found matching: [query]"

• The movie might not be in TMDB's database
• Try simplifying your query to just the movie title
• Check for typos in movie names

"Error retrieving movie information"

• Check your internet connection
• Verify your API key is valid at TMDB Settings
• Check the server logs for detailed error messages

Server doesn't start

• Verify Python version: python --version (should be 3.10+)
• Reinstall dependencies: pip install -r requirements.txt --force-reinstall
• Check for port conflicts or permission issues

Development and Testing

Running Tests Manually

You can test the TMDB client functionality:

import asyncio
import os
from server import TMDBClient

async def test():
    api_key = os.getenv("TMDB_API_KEY")
    client = TMDBClient(api_key)

    # Test search
    results = await client.search_movies("Rounders")
    print(f"Found {len(results)} results")

    if results:
        # Test details
        details = await client.get_movie_details(results[0]['id'])
        print(f"Title: {details['title']}")
        print(f"Rating: {details['vote_average']}/10")

    await client.close()

asyncio.run(test())

Adding Features

To add new tools or capabilities:

1. Add a new method to TMDBClient for the API call
2. Add a new tool definition in list_tools()
3. Add a handler in call_tool()
4. Update this README with the new functionality

Security Considerations

• Never commit your .env file - it contains your API key
• The .gitignore file is configured to exclude .env
• When sharing, always use .env.example as a template
• Rotate your API key if it's accidentally exposed

Resources

• The Movie Database API Documentation
• Model Context Protocol Specification
• MCP Python SDK

License

This project is provided as-is for educational and evaluation purposes.

Support

For issues with:

• This MCP server: Review the code and troubleshooting section
• TMDB API: Visit TMDB Support
• MCP Protocol: Check MCP Documentation

Note: This server was created as a demonstration of MCP integration with external APIs. It showcases proper error handling, asynchronous programming, and clean architecture principles suitable for production use.