moviefinder-mcp

An MCP server that wraps The Movie Database (TMDB) API. Built with @modelcontextprotocol/sdk and stdio transport.

Tools

Tool	Description
search_movies	Search movies by title, optional year filter.
search_tv	Search TV shows by title.
get_movie_details	Full movie details with top cast, directors, and trailer.
get_recommendations	TMDB recommendations for a movie.
get_similar	Movies similar to a given movie.
get_trending	Trending movie / tv / all for day or week.
where_to_stream	Streaming / rental / purchase providers for a movie (default country US).
discover_movies	Discover by genre name, min rating, year, and sort order.

All tools return summarized JSON (id, title, year, overview, rating, poster URL, etc.) — the noisy raw TMDB fields are stripped.

Setup

1. Get a TMDB API token

1. Create a free account at https://www.themoviedb.org/.
2. Visit https://www.themoviedb.org/settings/api and copy the API Read Access Token (v4). This is a long JWT — it is not the v3 API key.

2. Install and build

npm install
npm run build

3. Configure environment

Copy .env.example to .env and paste your token:

cp .env.example .env

TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. Run the server

npm start

The server speaks MCP over stdio and is meant to be launched by an MCP client (such as Claude Desktop), not run interactively.

Register with Claude Desktop

Add an entry to 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": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

Restart Claude Desktop after editing the config. The moviefinder tools will then appear in any conversation.

Scripts

Script	What it does
npm run build	Compiles TypeScript to dist/.
npm start	Runs the compiled server (node dist/index.js).
npm run dev	TypeScript watch mode.

Error handling

The server returns helpful messages for common TMDB failures:

• 401 — token missing or wrong key type (must be v4 read access token).
• 404 — the requested movie / resource does not exist.
• 429 — rate limited; the Retry-After value is included when present.

Notes

• Genre list is fetched once from /genre/movie/list and cached in memory.
• Poster URLs use https://image.tmdb.org/t/p/w500.
• No database, no logging framework — by design.