<div align="center">

<img src="https://github.com/simentob.png" width="120" style="border-radius: 50%" />

# 🎬 TMDB MCP Server

**Et Model Context Protocol-prosjekt som gir Claude direkte tilgang til filmdatabasen TMDB**

[![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-FastMCP-blueviolet?style=for-the-badge)](https://github.com/modelcontextprotocol/python-sdk)
[![TMDB](https://img.shields.io/badge/API-TMDB-01B4E4?style=for-the-badge&logo=themoviedatabase&logoColor=white)](https://developer.themoviedb.org)
[![uv](https://img.shields.io/badge/Pakkebehandler-uv-DE5FE9?style=for-the-badge)](https://github.com/astral-sh/uv)
[![Lisens](https://img.shields.io/badge/Lisens-MIT-green?style=for-the-badge)](LICENSE)

</div>

---

## 🤔 Hva er dette?

Dette prosjektet kobler **Claude AI** til **The Movie Database (TMDB)** via **Model Context Protocol (MCP)**.

I stedet for å søke manuelt på nettet kan du spørre Claude direkte i chatten:

> *"Hva trender på film denne uken?"*
> *"Finn anmeldelser av Oppenheimer"*
> *"Søk etter norske thrillere fra 2023"*

Claude kaller riktig verktøy, henter data fra TMDB, og svarer deg — alt i samme samtale.

---

## 🏗️ Arkitektur

```
┌─────────────────────────┐
│   Claude Desktop / MCP  │
│         Klient          │
└────────────┬────────────┘
             │  stdio transport
             ▼
┌─────────────────────────┐
│        main.py          │  ← Starter MCP-serveren
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│        server.py        │  ← Definerer MCP-verktøyene (FastMCP)
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│       services.py       │  ← Kaller TMDB REST API
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│       TMDB API          │  ← Henter film- og seriedata
└─────────────────────────┘
```

| Fil | Rolle |
|-----|-------|
| `main.py` | Inngangspunkt — starter serveren over stdio |
| `server.py` | Alle MCP-verktøy definert med FastMCP-dekoratorer |
| `services.py` | Rene funksjoner som snakker med TMDB API |

---

## 🛠️ Tilgjengelige verktøy

Når Claude er koblet til, har den tilgang til disse verktøyene:

| Verktøy | Beskrivelse |
|---------|-------------|
| 🔍 `tmdb_search_movies` | Søk etter filmer på tittel, år, region og språk |
| 🎭 `tmdb_multi_search` | Søk på tvers av filmer, serier og personer |
| 📈 `tmdb_trending_search` | Hent det som trender i dag eller denne uken |
| ⭐ `tmdb_movie_reviews` | Hent brukeranmeldelser for en film |
| 📺 `tmdb_tv_reviews` | Hent brukeranmeldelser for en TV-serie |
| 📝 `tmdb_review_details` | Hent fullstendige detaljer for én anmeldelse via ID |

---

## 🚀 Kom i gang

### 1. Forutsetninger

- Python 3.12+
- [uv](https://github.com/astral-sh/uv) installert
- En TMDB API-nøkkel (gratis — se nedenfor)

### 2. Skaff en TMDB API-nøkkel

1. Gå til [themoviedb.org](https://www.themoviedb.org/) og opprett en konto
2. Gå til **Innstillinger → API** og be om en API-nøkkel
3. Kopier **Bearer-tokenet** (den lange nøkkelen kalt "API Read Access Token")

![TMDB abonnementsskjermbilde](public/subscribe_screenshot.png)

### 3. Klon og installer

```bash
git clone https://github.com/simentob/movies-mcp-server.git
cd movies-mcp-server
uv sync
```

### 4. Konfigurer API-nøkkelen

Opprett en `.env`-fil i prosjektmappen:

```env
TMDB_API_KEY="din_bearer_token_her"
```

![.env oppsett](public/env_key.png)

### 5. Start serveren

```bash
uv run main.py
```

Du skal se:
```
Starting MCP server...
```

---

## 🖥️ Koble til Claude Desktop

Rediger konfigurasjonsfilen for Claude Desktop:

**macOS** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "tmdb-server": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "/ABSOLUTT/STI/TIL/movies-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}
```

**Windows** (`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "tmdb-server": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ABSOLUTT\\STI\\TIL\\movies-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}
```

Start Claude Desktop på nytt etter lagring. Verktøyene skal nå dukke opp i verktøyvelgeren.

---

## 💬 Eksempelsamtaler

Når Claude er koblet til kan du ha samtaler som dette:

> **Du:** Hva trender på film i dag?
>
> **Claude:** *(kaller `tmdb_trending_search`)* Her er dagens trendende filmer: ...

> **Du:** Finn anmeldelser av "Interstellar"
>
> **Claude:** *(kaller `tmdb_search_movies` og deretter `tmdb_movie_reviews`)* Her er anmeldelsene for Interstellar: ...

> **Du:** Søk etter koreanske thrillere
>
> **Claude:** *(kaller `tmdb_multi_search`)* Fant flere koreanske thrillere: ...

---

## 📁 Prosjektstruktur

```
movies-mcp-server/
├── main.py           # Starter MCP-serveren
├── server.py         # MCP-verktøy (FastMCP)
├── services.py       # TMDB API-funksjoner
├── pyproject.toml    # Prosjektavhengigheter
├── .env              # API-nøkkel (ikke committet)
├── public/
│   ├── subscribe_screenshot.png
│   └── env_key.png
└── README.md
```

---

## 📌 Merknader

- Dette prosjektet er **ikke tilknyttet TMDB**. Du må bruke din egen API-nøkkel.
- Serveren bruker **stdio-transport**, som er standarden for lokale MCP-servere.
- API-nøkler lastes fra `.env` og skrives aldri rett inn i koden — commit aldri `.env`-filen din.
- Les mer om MCP på [modelcontextprotocol.io](https://modelcontextprotocol.io) og i [MCP servers-repoet](https://github.com/modelcontextprotocol/servers).

---

<div align="center">

Laget av [simentob](https://github.com/simentob)

</div>