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

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.