moviefinder-mcp

An MCP server that wraps the TMDB API so an MCP-aware client (Claude Desktop, Claude Code, etc.) can search movies and TV, look up details, find what's trending, get recommendations, and check where a title is streaming.

Tools

Tool	Description
search_movies	Search movies by title; optional year.
search_tv	Search TV shows by name.
get_movie_details	Movie details with cast, director, and trailer URL.
get_recommendations	TMDB recommendations for a movie ID.
get_similar	Movies similar to a movie ID.
get_trending	Trending movie / tv / all for day or week.
where_to_stream	Watch providers (stream / rent / buy) by country (default US).
discover_movies	Discover by genre name, min_rating, year, sort_by.

All tools return summarized JSON (id, title, year, overview, rating, poster URL, plus tool-specific fields) instead of raw TMDB payloads.

Setup

Requirements: Node 20+.

npm install
cp .env.example .env
# edit .env and paste your TMDB v4 read access token
npm run build
npm start    # runs the compiled server over stdio

Getting a TMDB API key

1. Create a TMDB account at https://www.themoviedb.org/.
2. Open https://www.themoviedb.org/settings/api.
3. Copy the API Read Access Token (v4 auth) — not the v3 API key.
4. Put it in .env as TMDB_API_KEY=....

The server sends it as Authorization: Bearer <token>.

Register with Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "moviefinder": {
      "command": "node",
      "args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "your_v4_read_access_token_here"
      }
    }
  }
}

Restart Claude Desktop. The tools above will appear under the moviefinder server.

Notes

• The genre list (/genre/movie/list) is fetched once and cached in memory for discover_movies.
• 401 / 404 / 429 responses are surfaced with actionable messages.
• Inputs are validated with zod before any TMDB call.