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

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

# Get trending shows: auto-paginate up to 10 results
fetch_trending_shows(limit=10)

# Get trending shows: fetch ALL results (no limit)
fetch_trending_shows(limit=0)

# Get trending shows: single page with pagination metadata
fetch_trending_shows(limit=10, page=1)

# Get popular shows with optional limit parameter
fetch_popular_shows(limit=10)

# Get anticipated shows with optional limit parameter
fetch_anticipated_shows(limit=10)

# Get favorited shows with optional limit and period parameters
fetch_favorited_shows(limit=10, period="weekly")

# Get most played shows with optional limit and period parameters
fetch_played_shows(limit=10, period="weekly")

# Get most watched shows with optional limit and period parameters
fetch_watched_shows(limit=10, period="weekly")

# Search for shows: auto-paginate all results (omit page parameter)
search_shows(query="Breaking Bad", limit=5)

# Search for shows: single page with pagination metadata
search_shows(query="Breaking Bad", limit=5, page=1)

# Get ratings for a show
fetch_show_ratings(show_id="game-of-thrones")

# Get comprehensive show summary (includes air times, production status, ratings, metadata)
fetch_show_summary(show_id="game-of-thrones", extended=True)  # Default: comprehensive

# Get basic show summary (title, year, ID only)
fetch_show_summary(show_id="game-of-thrones", extended=False)

# Get videos for a show (with embedded markdown - default)
fetch_show_videos(show_id="game-of-thrones")

# Get videos for a show (simple text links)
fetch_show_videos(show_id="game-of-thrones", embed_markdown=False)

# Get related shows (similar shows based on genres, themes, and viewer patterns)
fetch_related_shows(show_id="game-of-thrones", limit=10)

# Get related shows with pagination metadata
fetch_related_shows(show_id="game-of-thrones", limit=10, page=1)

# Get all seasons for a show (includes episode counts, aired episodes, ratings)
fetch_show_seasons(show_id="game-of-thrones")

# Get cast and crew for a show
fetch_show_people(show_id="breaking-bad")

# Get cast, crew, and guest stars for a show
fetch_show_people(show_id="breaking-bad", include_guest_stars=True)

# Search for movies: auto-paginate all results (omit page parameter)
search_movies(query="The Godfather", limit=5)

# Search for movies: single page with pagination metadata
search_movies(query="The Godfather", limit=5, page=1)

# Get detailed info about a specific season
fetch_season_info(show_id="breaking-bad", season=1)

# Get all episodes for a season with ratings and runtime
fetch_season_episodes(show_id="breaking-bad", season=1)

# Get ratings and voting distribution for a season
fetch_season_ratings(show_id="breaking-bad", season=1)

# Get engagement stats (watchers, plays, collectors)
fetch_season_stats(show_id="breaking-bad", season=1)

# Get cast and crew for a season
fetch_season_people(show_id="breaking-bad", season=1)

# Get videos/trailers for a season (with embedded markdown - default)
fetch_season_videos(show_id="breaking-bad", season=1)

# Get videos for a season (simple text links)
fetch_season_videos(show_id="breaking-bad", season=1, embed_markdown=False)

# See who's watching a season right now
fetch_season_watching(show_id="breaking-bad", season=1)

# Get translations for a season (all languages)
fetch_season_translations(show_id="breaking-bad", season=1)

# Get translations for a specific language
fetch_season_translations(show_id="breaking-bad", season=1, language="es")

# Get lists containing a season
fetch_season_lists(show_id="breaking-bad", season=1)

# Get lists with type and sort filters
fetch_season_lists(show_id="breaking-bad", season=1, list_type="personal", sort="popular")

# Get detailed info about a specific episode
fetch_episode_summary(show_id="breaking-bad", season=1, episode=1)

# Get ratings and voting distribution for an episode
fetch_episode_ratings(show_id="breaking-bad", season=1, episode=1)

# Get engagement stats (watchers, plays, collectors)
fetch_episode_stats(show_id="breaking-bad", season=1, episode=1)

# Get cast and crew for an episode
fetch_episode_people(show_id="breaking-bad", season=1, episode=1)

# Get videos/trailers for an episode (with embedded markdown - default)
fetch_episode_videos(show_id="breaking-bad", season=1, episode=1)

# Get videos for an episode (simple text links)
fetch_episode_videos(show_id="breaking-bad", season=1, episode=1, embed_markdown=False)

# See who's watching an episode right now
fetch_episode_watching(show_id="breaking-bad", season=1, episode=1)

# Get translations for an episode (all languages)
fetch_episode_translations(show_id="breaking-bad", season=1, episode=1)

# Get translations for a specific language
fetch_episode_translations(show_id="breaking-bad", season=1, episode=1, language="es")

# Get lists containing an episode
fetch_episode_lists(show_id="breaking-bad", season=1, episode=1)

# Get lists with type and sort filters
fetch_episode_lists(show_id="breaking-bad", season=1, episode=1, list_type="personal", sort="popular")

# Get trending movies: auto-paginate all results (omit page parameter)
fetch_trending_movies(limit=10)

# Get trending movies: single page with pagination metadata
fetch_trending_movies(limit=10, page=1)

# Get popular movies with optional limit parameter
fetch_popular_movies(limit=10)

# Get anticipated movies with optional limit parameter
fetch_anticipated_movies(limit=10)

# Get favorited movies with optional limit and period parameters
fetch_favorited_movies(limit=10, period="weekly")

# Get most played movies with optional limit and period parameters
fetch_played_movies(limit=10, period="weekly")

# Get most watched movies with optional limit and period parameters
fetch_watched_movies(limit=10, period="weekly")

# Get the top 10 U.S. box office movies from last weekend
fetch_boxoffice_movies()

# Get ratings for a movie
fetch_movie_ratings(movie_id="tron-legacy-2010")

# Get comprehensive movie summary (includes production status, ratings, genres, runtime, certification, metadata)
fetch_movie_summary(movie_id="tron-legacy-2010", extended=True)  # Default: comprehensive

# Get basic movie summary (title, year, ID only)
fetch_movie_summary(movie_id="tron-legacy-2010", extended=False)

# Get videos for a movie (with embedded markdown - default)
fetch_movie_videos(movie_id="tron-legacy-2010")

# Get videos for a movie (simple text links)
fetch_movie_videos(movie_id="tron-legacy-2010", embed_markdown=False)

# Get related movies (similar movies based on genres, themes, and viewer patterns)
fetch_related_movies(movie_id="tron-legacy-2010", limit=10)

# Get related movies with pagination metadata
fetch_related_movies(movie_id="tron-legacy-2010", limit=10, page=1)

# Get cast and crew for a movie
fetch_movie_people(movie_id="the-dark-knight-2008")

# Get extended person details (biography, social media, birthday)
fetch_person_summary(person_id="bryan-cranston")

# Get basic person details (name and IDs only)
fetch_person_summary(person_id="bryan-cranston", extended=False)

# Look up by IMDB ID
fetch_person_summary(person_id="nm0186505")

# Get all movie credits for a person (cast roles and crew positions)
fetch_person_movies(person_id="bryan-cranston")

# Get all show credits for a person (with episode counts and series regular flags)
fetch_person_shows(person_id="bryan-cranston")

# Get lists containing a person (all types, sorted by popularity)
fetch_person_lists(person_id="bryan-cranston")

# Get lists with type and sort filters
fetch_person_lists(person_id="bryan-cranston", list_type="personal", sort="likes")

# Start the device authorization flow with Trakt
start_device_auth()

# Check the status of an ongoing authentication
check_auth_status()

# Clear authentication (logout)
clear_auth()

# Fetch shows watched by the authenticated user
fetch_user_watched_shows(limit=0)  # 0 for all shows

# Fetch movies watched by the authenticated user
fetch_user_watched_movies(limit=0)  # 0 for all movies

# Fetch user's personal ratings with pagination support
fetch_user_ratings(rating_type="movies", rating=10, page=1)

# Add new ratings for movies, shows, seasons, or episodes
add_user_ratings(rating_type="movies", items=[{"trakt_id": "314", "rating": 9}])

# Remove existing ratings by ID
remove_user_ratings(rating_type="movies", items=[{"trakt_id": "314"}])

# Fetch user's watchlist with pagination and sorting
fetch_user_watchlist(watchlist_type="all", sort_by="rank", sort_how="asc", page=1)

# Add items to watchlist with optional notes (VIP)
add_user_watchlist(watchlist_type="movies", items=[{"trakt_id": "314", "notes": "Must watch!"}])

# Remove items from watchlist
remove_user_watchlist(watchlist_type="movies", items=[{"trakt_id": "314"}])

# Method 1: Check in using show ID (recommended when precision is important)
# First use search_shows to find the correct show ID
search_shows(query="Breaking Bad", limit=5)
# Then use the ID for check-in
checkin_to_show(
    season=1,
    episode=3,
    show_id="1388",
    message="Loving this show!"
)

# Method 2: Check in using show title (more convenient)
checkin_to_show(
    season=1,
    episode=1,
    show_title="Breaking Bad",
    show_year=2008,  # Optional but helps with accuracy
    message="I'm the one who knocks!"
)

# Get comments for a movie: auto-paginate all results (omit page parameter)
fetch_movie_comments(movie_id="123", limit=10, show_spoilers=False)

# Get comments for a movie: single page with pagination metadata
fetch_movie_comments(movie_id="123", limit=10, show_spoilers=False, page=1)

# Get comments for a show: auto-paginate all results (omit page parameter)
fetch_show_comments(show_id="456", limit=10, show_spoilers=False, sort="likes")

# Get comments for a show: single page with pagination metadata
fetch_show_comments(show_id="456", limit=10, show_spoilers=False, sort="likes", page=1)

# Get comments for a specific season sorted by highest rating
fetch_season_comments(show_id="456", season=1, limit=10, show_spoilers=False, sort="highest")

# Get comments for a specific episode sorted by most replies
fetch_episode_comments(show_id="456", season=1, episode=3, limit=10, show_spoilers=False, sort="replies")

# Get a specific comment
fetch_comment(comment_id="789", show_spoilers=False)

# Get a comment with its replies sorted by oldest first
fetch_comment_replies(comment_id="789", limit=10, show_spoilers=False, sort="oldest")

# Get watched progress for a TV show
fetch_show_progress(show_id="breaking-bad")

# Get show progress with specials and hidden seasons included
fetch_show_progress(
    show_id="game-of-thrones",
    hidden=True,       # Include hidden seasons
    specials=True,     # Include season 0 (specials)
    count_specials=True,  # Count specials in overall stats
    last_activity="watched"  # Calculate next episode based on watched order
)

# Get detailed episode-by-episode progress with watch dates
fetch_show_progress(show_id="breaking-bad", verbose=True)

# Get paused playback progress (all types)
fetch_playback_progress()

# Get paused playback progress (movies only)
fetch_playback_progress(playback_type="movies")

# Get paused playback progress (episodes only)
fetch_playback_progress(playback_type="episodes")

# Remove a paused playback item (get ID from fetch_playback_progress)
remove_playback_item(playback_id=12345)

# Check if a movie has been watched (returns watch dates and count)
fetch_history(history_type="movies", item_id="314")  # The Dark Knight

# Check watch history for a show
fetch_history(history_type="shows", item_id="1388")  # Breaking Bad

# Browse all movie watch history
fetch_history(history_type="movies")

# Browse all watch history (all types)
fetch_history()

# Filter history by date range
fetch_history(
    history_type="movies",
    start_at="2024-01-01T00:00:00.000Z",
    end_at="2024-12-31T23:59:59.000Z"
)

# Add movies to watch history
add_to_history(
    history_type="movies",
    items=[{"trakt_id": "314"}]  # The Dark Knight
)

# Add movies with custom watched date
add_to_history(
    history_type="movies",
    items=[{"trakt_id": "314", "watched_at": "2024-01-15T20:30:00.000Z"}]
)

# Add episodes to watch history
add_to_history(
    history_type="episodes",
    items=[{"trakt_id": "62085"}]  # Breaking Bad S01E01
)

# Remove movies from watch history
remove_from_history(
    history_type="movies",
    items=[{"trakt_id": "314"}]
)

# Remove episodes from watch history
remove_from_history(
    history_type="episodes",
    items=[{"trakt_id": "62085"}]
)