cinelens-mcp

An MCP server for movie and TV discovery, powered by TMDB, TVmaze, and Watchmode.

A standalone FastMCP server, extracted from the CineLens conversational movie agent. Bring your own API keys (BYOK) — nothing is bundled or hardcoded.

Features

Movies

• search_movie_tool — search TMDB by title
• discover_recent_movies_tool — browse by real release date ("recent"/"latest"/"new")
• discover_by_genre_tool — browse by genre, optionally within a recent window
• search_person_tool — find an actor or director by name
• get_person_credits_tool — list a person's movie credits, newest first
• select_movie_tool — switch the active movie to a specific candidate
• get_movie_details_tool — details for the active movie
• get_cast_tool — cast for the active movie
• get_recommendations_tool — recommendations similar to the active movie
• get_watch_providers_tool — where to stream/rent/buy the active movie

TV Shows

• search_tv_show_tool — search TVmaze by title (free, no API key required)
• get_show_details_tool — name, status, genres, rating, network, schedule, summary
• get_show_streaming_tool — streaming sources grouped by free/subscription/rent/buy

Theatres

• get_now_playing_tool — up to 10 movies currently playing in theatres
• get_trending_tool — top 10 trending movies for "day" or "week"

Quickstart (Claude Desktop)

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "cinelens": {
      "command": "uvx",
      "args": ["cinelens-mcp"],
      "env": {
        "TMDB_API_KEY": "your-tmdb-bearer-token",
        "DEFAULT_REGION": "US",
        "WATCHMODE_API_KEY": "your-watchmode-api-key"
      }
    }
  }
}

Restart Claude Desktop, then ask it to search for a movie — it will call search_movie_tool first automatically, then any other tools.

Environment variables

TVmaze tools (search_tv_show_tool, get_show_details_tool) need no key.

Bring Your Own Key (BYOK)

cinelens-mcp ships with no embedded credentials. Every tool that calls a paid or rate-limited API reads its key from an environment variable at call time, not at import time — so the server starts and lists its tools fine even with no keys configured, and only fails the specific tool call that needed a missing key. This keeps the package free to distribute, puts API usage and billing under each user's own account, and means a key never has to be committed, bundled, or shared to use the server. Keys are read only by the module that owns the corresponding backend (see backends/) and are never logged or included in a tool response or error message.

Tool reference

How it works: prerequisite middleware

Tools that depend on an active movie or TV show (e.g. get_cast_tool, get_show_details_tool) require an entry-point tool to have run first in the same session. This is not enforced by instructing the model in a system prompt — LLMs occasionally skip or misorder steps when the rule lives only in text. Instead, middleware/prerequisites.py checks session state programmatically before every gated tool executes, keyed off fields on MovieSessionState (movie_id, show_id, last_candidates) that are only ever set by a successful upstream call.

If the prerequisite isn't met, the tool call is short-circuited and returns a structured error instead of hitting the backend:

{
  "error": "prerequisite_not_met",
  "message": "Please search for a movie first.",
  "required_tool": "search_movie"
}

The movie chain and TV chain gate independently — an active movie doesn't satisfy a TV prerequisite and vice versa. This makes the dependency graph a property of the code, not a hope about model behavior, so it holds under any client and any prompt.

Reliability

TMDB requests automatically retry on 429/5xx with exponential backoff (3 retries, respecting Retry-After); persistent rate limiting raises TMDBRateLimitError rather than failing silently.

Install & run

uvx cinelens-mcp

Or from source:

uv sync
uv run cinelens-mcp

Development

uv sync
uv run pytest

See CONTRIBUTING.md for how to add a new tool or data source.

License

MIT — see LICENSE.