movie-xray-mcp

A FastMCP server that gives Claude an Amazon Prime "X-Ray"-style view of movies and TV shows: look up a title, see the cast, drill into an actor's bio and filmography, find out what else of theirs is on Netflix right now, and link out to IMDb for more detail.

Ask Claude things like:

• "Search for The Matrix and tell me about the cast"
• "Who plays Neo, and what else has Keanu Reeves been in?"
• "Is anything from Keanu Reeves' filmography on Netflix right now?"
• "What's the IMDb rating and Rotten Tomatoes score for Oppenheimer?"
• "Show me everything streaming for The Bear, with cast and IMDb links"

---

Tools

Tool	Description	Auth required
search_title	Search for a movie or TV show	No
get_title_details	Synopsis, cast, ratings, IMDb link, and streaming availability	No
get_actor_info	Actor bio, photo, and IMDb link	No
get_actor_filmography	An actor's filmography, sorted by popularity	No
get_watch_providers	Where a title is streaming/renting/buying (incl. Netflix)	No
get_actor_netflix_titles	Cross-references an actor's filmography against Netflix's catalog	No

Everything here uses public catalog data — no Spotify-style OAuth login is needed.

---

Prerequisites

• Python 3.10+ (required by FastMCP and the underlying MCP SDK — see below if you're not sure what you have)
• A free TMDb account and API key
• A free OMDb API key (optional — adds IMDb/Rotten Tomatoes/Metacritic ratings and plot text to get_title_details)

Checking your Python version

python3 --version

If this prints 3.10.x, 3.11.x, 3.12.x, or 3.13.x, you're good — skip to Step 1.

If it prints 3.9.x or lower (common on macOS, which ships an old system Python), you need to install a newer Python before creating the virtual environment in Step 3. pip install -r requirements.txt will fail with Could not find a version that satisfies the requirement fastmcp>=2.0 if you try to use Python 3.9 or earlier.

Installing Python 3.10+

macOS (Homebrew):

brew install python@3.12

This installs a separate python3.12 binary alongside your system Python — it won't replace or break anything else. Verify with:

python3.12 --version

macOS (no Homebrew): Download the installer from python.org/downloads and run it. After installing, use python3.12 (or whichever version you installed) in place of python3 below.

Windows: Download the installer from python.org/downloads, run it, and check "Add python.exe to PATH" during install. Verify with:

python --version

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install python3.12 python3.12-venv

Using pyenv (any OS, if you manage multiple Python versions):

pyenv install 3.12.7
pyenv local 3.12.7   # sets this version for the movie-xray-mcp directory

Once you have a 3.10+ interpreter available, use that binary (e.g. python3.12) instead of python3 when creating the virtual environment in Step 3.

---

Step 1: Get a TMDb API key

1. Create a free account at themoviedb.org
2. Go to Settings → API (themoviedb.org/settings/api)
3. Request an API key (choose "Developer" — instant approval for personal use)
4. Copy the API Key (v3 auth) value

---

Step 2: Get an OMDb API key (optional)

1. Go to omdbapi.com/apikey.aspx
2. Select the free tier and enter your email
3. Activate the key via the email OMDb sends you

If you skip this, get_title_details still works — it just won't include the ratings field (IMDb rating, Rotten Tomatoes, Metascore, plot, etc.).

---

Step 3: Local Setup

cd movie-xray-mcp

# Create virtual environment using Python 3.10+
# If `python3 --version` showed 3.10+, use python3 below.
# Otherwise, substitute the 3.10+ binary you installed above (e.g. python3.12).
python3 -m venv .venv
source .venv/bin/activate        # Mac/Linux
# .venv\Scripts\activate         # Windows

# Confirm the venv is using Python 3.10+
python --version

# Install dependencies
pip install -r requirements.txt

# Copy env template and fill in your keys
cp .env.example .env

If pip install -r requirements.txt fails with Could not find a version that satisfies the requirement fastmcp>=2.0, your venv was created with Python <3.10. Delete it and recreate using a 3.10+ binary:

rm -rf .venv
python3.12 -m venv .venv   # use whichever 3.10+ binary you installed
source .venv/bin/activate
pip install -r requirements.txt

Edit .env:

TMDB_API_KEY=your_tmdb_v3_api_key_here
OMDB_API_KEY=your_omdb_api_key_here
DEFAULT_REGION=US

DEFAULT_REGION is an ISO 3166-1 country code used by default for streaming availability (e.g. US, GB, CA). It can be overridden per-call on any tool that takes a region argument.

---

Step 4: Run Locally

Option A: stdio (for Claude Desktop)

python server.py
# or explicitly:
python server.py stdio

Option B: SSE (for Railway / remote clients)

python server.py sse
# Server starts on http://localhost:8000

---

Step 5: Connect to Claude Desktop

Add this to your Claude Desktop config file:

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

{
  "mcpServers": {
    "movie-xray-mcp": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/movie-xray-mcp/server.py"],
      "env": {
        "TMDB_API_KEY": "your_tmdb_v3_api_key_here",
        "OMDB_API_KEY": "your_omdb_api_key_here",
        "DEFAULT_REGION": "US"
      }
    }
  }
}

Replace /absolute/path/to/ with your actual paths.

Restart Claude Desktop after saving. You should see movie-xray-mcp in the tools list.

---

Step 6: Deploy to Railway

First-time setup

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Initialize project
railway init

# Set environment variables
railway variables set TMDB_API_KEY=your_tmdb_v3_api_key_here
railway variables set OMDB_API_KEY=your_omdb_api_key_here
railway variables set DEFAULT_REGION=US

Deploy

railway up

Railway reads railway.toml and automatically:

• Detects Python via Nixpacks
• Installs requirements.txt
• Runs python server.py sse
• Sets PORT environment variable

Get your deployed URL

railway domain
# Returns something like: https://movie-xray-mcp-production.up.railway.app

Connect Claude to your Railway deployment

Once deployed, your MCP server is accessible via SSE at:

https://your-app.railway.app/sse

Add this to your Claude Desktop config:

{
  "mcpServers": {
    "movie-xray-mcp": {
      "url": "https://your-app.railway.app/sse"
    }
  }
}

---

Project Structure

movie-xray-mcp/
├── server.py          # FastMCP server — all tools live here
├── requirements.txt   # Python dependencies
├── railway.toml       # Railway deployment config
├── .env.example       # Environment variable template
├── .env               # Your actual API keys (gitignored)
└── README.md          # This file

---

Example Prompts for Claude

Once connected, try these:

Search for "The Bear" and give me an overview.

Who's in the cast of Oppenheimer, and what are their IMDb pages?

What's the IMDb rating, Rotten Tomatoes score, and plot summary for Dune: Part Two?

Tell me about Zendaya — bio, IMDb link, and her most popular roles.

Is anything from Pedro Pascal's filmography currently on Netflix in the US?

Where can I stream The Matrix — is it on Netflix?

---

Notes on Rate Limits & Performance

• TMDb: generous free-tier limits, suitable for personal/demo use.
• OMDb: free tier is limited to 1,000 requests/day. get_title_details only calls OMDb once per title (and skips it entirely if OMDB_API_KEY isn't set or the IMDb ID can't be resolved).
• get_actor_netflix_titles: checks the actor's top_n most popular credits (default 15) against Netflix's catalog for region. Each credit checked is one extra TMDb call, so raising top_n trades speed for completeness — most users only care about an actor's well-known work, which top_n=15 already covers.

---

Architecture Notes

• TMDb (themoviedb.org) powers search, cast/crew, filmographies, IMDb ID resolution, and watch/providers (JustWatch-sourced streaming availability, including Netflix, by region).
• OMDb (omdbapi.com) optionally enriches title details with IMDb/Rotten Tomatoes/Metacritic ratings and plot text.
• FastMCP handles the MCP protocol — all tools are decorated with @mcp.tool().
• Transport is switchable: stdio for local/Claude Desktop, sse for Railway/remote.
• Railway auto-detects Python via Nixpacks — no Dockerfile needed.

---

Built With

• FastMCP — MCP server framework
• TMDb API — movie/TV metadata, cast, and streaming availability
• OMDb API — IMDb/Rotten Tomatoes/Metacritic ratings
• Railway — deployment platform