# moviefinder-mcp

An MCP server that wraps [The Movie Database (TMDB)](https://www.themoviedb.org/) 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

```bash
npm install
npm run build
```

### 3. Configure environment

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

```bash
cp .env.example .env
```

```env
TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...
```

### 4. Run the server

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

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