🎬 MCP Trakt: Your AI's Gateway to Entertainment Data

A Model Context Protocol (MCP) server that creates a bridge between AI language models and the Trakt.tv API, allowing LLMs to access real-time entertainment data and personal Trakt viewing history. Built with a domain-focused architecture using FastMCP, providing clean separation of concerns across authentication, shows, seasons, episodes, movies, people, user data, comments, search, and check-in functionality.

🖥️ An AI Experiment

Other than this paragraph, everything here has been generated by AI, including the code. I had a goal to learn more about MCP and have been playing a lot with Cursor, so it seemed like a natural next move to bring these together. The result was this project. All changes moving forward will also be done by AI.

📚 About MCP & Trakt

Model Context Protocol (MCP) enables AI models to interact with external systems through standardized tools and resources. Trakt.tv is a comprehensive platform for tracking TV shows and movies with 14+ million users and extensive APIs for developers.

🚀 Quick Start

Docker Quickstart

docker run -d --rm --name trakt_mcpserver \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -v trakt_auth:/data \
  -p 8080:8080 \
  ghcr.io/wwiens/trakt_mcpserver:latest

Run with uvx (no clone, no install)

Requires uv installed.

uvx --from git+https://github.com/wwiens/trakt_mcpserver trakt-mcp

Pin to a release tag for reproducibility:

uvx --from git+https://github.com/wwiens/trakt_mcpserver@v0.9.0 trakt-mcp

Claude Desktop / MCPhub configuration:

{

  "mcpServers": {

    "trakt": {

      "command": "uvx",

      "args": [

        "--from",

        "git+https://github.com/wwiens/trakt_mcpserver",

        "trakt-mcp"

      ],

      "env": {

        "TRAKT_CLIENT_ID": "your_client_id",

        "TRAKT_CLIENT_SECRET": "your_client_secret"

      }

    }

  }

}

Your Trakt OAuth token is persisted to ~/.trakt-mcp/auth_token.json (the directory is created on first login), so authorization survives across uvx invocations. To override the location — e.g. for Docker volumes or to keep multiple isolated accounts — set TRAKT_AUTH_TOKEN_PATH to an absolute path.

Local Installation

Requires Python 3.12 or newer.

1. Clone this repository

   git clone https://github.com/wwiens/trakt_mcpserver.git

   cd trakt_mcpserver

   

2. Create a virtual environment and install dependencies

   python3 -m venv .venv

   source .venv/bin/activate

   pip install -e .

   

3. Set up your environment

   cp .env.example .env

   

Then edit .env to add your Trakt API credentials:

   TRAKT_CLIENT_ID=your_client_id

   TRAKT_CLIENT_SECRET=your_client_secret

   

4. Run the server

   python server.py

   

Installing in Claude Desktop

Add to your Claude Desktop MCP configuration file:

{
  "mcpServers": {
    "trakt": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "TRAKT_CLIENT_ID": "your_client_id",
        "TRAKT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

✨ Features

🌎 Public Trakt Data

- Access trending and popular shows and movies - Discover the most anticipated, favorited, played, and watched content - See the top-grossing U.S. box office movies from last weekend - Get real-time data from Trakt's global community - Formatted responses with titles, years, and popularity metrics - View detailed ratings for shows and movies including average scores and distribution - Browse show seasons with episode counts, aired episodes, and ratings per season - Dive into specific seasons with detailed info, episode lists, ratings, cast & crew, videos, translations, and engagement stats - See who's watching a specific season right now - Find lists containing a specific season - Explore individual episodes with detailed summaries, ratings, cast & crew, videos, translations, and engagement stats - See who's watching a specific episode right now - Find lists containing a specific episode - Look up cast and crew for any movie or show, with optional guest stars for shows - Explore people with biographies, social media, and full filmographies - Browse a person's credits across movies and shows with character names and episode counts - Find lists containing a specific person

👤 Personal Trakt Data

- View Your Watched Shows: Get a complete list of shows you've personally watched - See your exact last-watched dates for each series - Track how many times you've watched each show - Check in to shows you're currently watching to mark them as watched - By show ID (more precise) or show title (more convenient) - Include custom messages with your check-ins - See when you watched the episode in human-readable format - Search for shows to find their details and IDs - Manage your ratings: View, add, and remove personal ratings for movies, shows, seasons, and episodes with pagination support - Manage your watchlist: View, add, and remove items from your watchlist with pagination and sorting support - Filter by type (all, movies, shows, seasons, episodes) - Sort by multiple criteria (rank, added, title, released, runtime, popularity, percentage, votes) - Add optional notes to watchlist items (VIP feature, 500 char limit) - Track show progress: See your watched progress for any TV show - View episodes watched vs aired with completion percentage - See your next episode to watch - View per-season breakdown with progress stats - Include hidden seasons and specials optionally - Manage playback progress: View and clear paused playback items - See movies and episodes you paused mid-watch - View progress percentage and when you paused - Clear playback items you no longer need - Manage watch history: Add and remove items from your history - Mark movies, shows, seasons, or episodes as watched - Optionally specify when you watched them - Remove items from your watch history - Secure authentication with Trakt through device code flow - Personal data is fetched directly from your Trakt account

🎯 Personalized Recommendations

- Get tailored movie and show suggestions based on your watch history and ratings (requires authentication) - Filter out items you've already collected or watchlisted - Hide recommendations you're not interested in so they don't come back - Unhide previously hidden items to restore them

💬 Comments & Reviews

- View comments for shows and movies: Read what others are saying about your favorite content - See comments for specific seasons and episodes: Get insights about particular parts of a show - View individual comments and their replies: Engage with the community's discussions - Spoiler protection: Comments with spoilers are hidden by default - Toggle spoiler visibility: Choose whether to show or hide spoilers - View reviews: Longer, more detailed comments are marked as reviews - See ratings distribution: View how many users gave each rating from 1-10

🔄 General Features

- Exposes Trakt API data through MCP resources - Provides tools for fetching real-time entertainment information - Enables AI models to offer personalized entertainment recommendations - Simple authentication and logout process - Pagination support for list endpoints (trending, popular, anticipated, favorited, played, watched, search, comments, ratings, watchlist): - Pass page: int for single-page results with pagination metadata - Omit page to auto-paginate and return up to limit total items as a flat list - Use limit=0 to fetch all available results (capped at 100 for safety)

🔥 Real-Time Trending Data

- Access currently trending TV shows with live viewer counts - Get trending movies updated in real-time - See what's popular across Trakt's global community of 14+ million users - Examples: The White Lotus (2021), Daredevil: Born Again (2025), Black Bag (2025)

🔌 Available Resources

MCP resources provide static data endpoints that AI models can access. These URIs expose Trakt data through a standardized interface.

<details>
<summary><strong>View all available resources</strong></summary>

Show Resources

| Resource | Description | Example Data | |----------|-------------|--------------| | trakt://shows/trending | Most watched shows over the last 24 hours | Show title, year, watchers count | | trakt://shows/popular | Most popular shows based on ratings | Show title, year, popular score | | trakt://shows/anticipated | Most anticipated shows sorted by list count | Show title, year, list count | | trakt://shows/favorited | Most favorited shows | Show title, year, favorites count | | trakt://shows/played | Most played shows | Show title, year, play count | | trakt://shows/watched | Most watched shows by unique users | Show title, year, watcher count |

Movie Resources

| Resource | Description | Example Data | |----------|-------------|--------------| | trakt://movies/trending | Most watched movies over the last 24 hours | Movie title, year, watchers count | | trakt://movies/popular | Most popular movies based on ratings | Movie title, year, popular score | | trakt://movies/anticipated | Most anticipated movies sorted by list count | Movie title, year, list count | | trakt://movies/favorited | Most favorited movies | Movie title, year, favorites count | | trakt://movies/played | Most played movies | Movie title, year, play count | | trakt://movies/watched | Most watched movies by unique users | Movie title, year, watcher count | | trakt://movies/boxoffice | Top 10 grossing U.S. box office movies last weekend | Movie title, year, revenue |

User Resources

| Resource | Description | Example Data | |----------|-------------|--------------| | trakt://user/auth/status | Current authentication status | Authentication status, token expiry | | trakt://user/watched/shows | Shows watched by the authenticated user | Show title, year, last watched date, play count | | trakt://user/watched/movies | Movies watched by the authenticated user | Movie title, year, last watched date, play count |

</details>

🛠️ Available Tools

MCP tools are interactive functions that AI models can call with parameters. Use these to fetch, search, and manage Trakt data.

<details>
<summary><strong>Show Tools</strong></summary>

```python