# moviefinder-mcp

An [MCP](https://modelcontextprotocol.io) server that wraps the
[TMDB](https://www.themoviedb.org/) 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+**.

```bash
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`):

```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.