film-tv-mcp

An MCP server for movie and TV lookups: search, full title and person detail, episode lists, discovery by genre, year, language or streaming service, where to watch in any country, and critic/audience scores from IMDb, Rotten Tomatoes, Metacritic, Letterboxd and more. Twelve read-only tools, built on the Python MCP SDK (FastMCP). Runs as a local stdio server or as a containerized Streamable HTTP service with bearer auth.

Providers:

Rotten Tomatoes has no public API (the official one is a paid partner licence), so its scores come through OMDb or MDBList.

Tool Reference

Titles are addressed by tmdb_id + kind (movie or tv). Every result row prints them as [movie 550] / [tv 1399], so a model can pass them straight back.

search(query="severance")                          # → [tv 95396]
title_details(tmdb_id=95396, kind="tv")            # cast, seasons, next episode, where to watch
discover(kind="tv", genres="Comedy", providers="Stan,Binge", sort_by="rating")
where_to_watch(tmdb_id=550, region="all")          # which countries stream it
ratings(tmdb_id=550)                               # IMDb, RT critics + audience, Metacritic, Letterboxd

Related MCP server: MCP JustWatch Server

Setup

1. TMDB (required): create a free account, then Settings → API → request an API key. Use the API Read Access Token (v4, a long JWT) as TMDB_API_TOKEN; the short v3 API Key also works as TMDB_API_KEY.

2. OMDb (optional): request a key at omdbapi.com (free tier: 1,000 requests/day) and set OMDB_API_KEY.

3. MDBList (optional): sign in at mdblist.com, copy the API key from Preferences and set MDBLIST_API_KEY. The free tier has a daily request cap; source_status(check_live=True) shows usage.

4. Set WATCH_REGION (e.g. AU) and TMDB_LANGUAGE (e.g. en-AU) for your country.

The server starts without any key: TMDB tools return a setup error, and ratings falls back to TMDB's own score until OMDb or MDBList is set.

Quick start (stdio)

Most MCP clients (Claude Code, Claude Desktop, VS Code, …) spawn stdio servers directly. With uv installed:

// e.g. Claude Desktop claude_desktop_config.json / Claude Code .mcp.json
{
  "mcpServers": {
    "film-tv": {
      "command": "uvx",
      "args": ["film-tv-mcp", "--stdio"],
      "env": {
        "TMDB_API_TOKEN": "your-read-access-token",
        "WATCH_REGION": "AU",
        "OMDB_API_KEY": "optional",
        "MDBLIST_API_KEY": "optional"
      }
    }
  }
}

stdio mode has no network surface and skips bearer auth — the client owns the process.

HTTP mode (container)

The bundled Containerfile builds a Streamable HTTP server at /mcp (stateless — restarts never strand client sessions). HTTP mode refuses to start without MCP_BEARER_TOKEN; clients authenticate with Authorization: Bearer <token>.

podman build -t film-tv-mcp .    # or: docker build -t film-tv-mcp .
podman run -d --name film-tv-mcp -p 8337:8337 \
  -e TMDB_API_TOKEN=... -e WATCH_REGION=AU -e MCP_BEARER_TOKEN=some-long-random-token \
  film-tv-mcp

film_tv_mcp.healthcheck does a full HTTP round-trip to /mcp (the 401 counts as alive — it proves the event loop responds); wire it to your container healthcheck with a restart-on-unhealthy policy. Terminate TLS at a reverse proxy — the server itself speaks plain HTTP.

Configuration

Architecture notes

• One thread-safe httpx.Client per provider. TMDB detail calls fold credits, external ids, videos, certifications and watch providers into one request with append_to_response.

• Genre and provider name→id tables are fetched once per process and cached. Name matching is case-insensitive; an exact name wins, otherwise every name containing the term matches (netflix also matches "Netflix Standard with Ads").

• Every tool is read-only: nothing writes to TMDB, OMDb or MDBList.

• Sync tool handlers are offloaded to a worker thread (the MCP SDK runs sync tools inline on the event loop, so a slow upstream call would otherwise stall every concurrent request). Per-request log lines (tool= outcome= duration_ms= rss_mib=) go to stderr.

• API-key values are redacted from error messages before they can reach logs or clients.

Testing

# Tiers 1 + 2 — pure helpers + mocked HTTP (fast, no network, no keys)
uv run --extra test pytest tests/test_tmdb_client.py tests/test_ratings_client.py -v

# Tier 3 — live, read-only round-trips. Each provider's tests skip
# without its key.
TMDB_API_TOKEN=... OMDB_API_KEY=... MDBLIST_API_KEY=... \
  uv run --extra test pytest tests/test_integration.py -v

Attribution

This product uses the TMDB API but is not endorsed or certified by TMDB. Where-to-watch data is provided by JustWatch via TMDB.

License

MIT