🎬 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, movies, 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_server \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -p 8080:8080 \
  ghcr.io/wwiens/trakt_mcpserver:latest

Local Installation

Clone this repository

git clone https://github.com/yourusername/mcp-trakt.git
cd mcp-trakt

Install dependencies
```
pip install -r requirements.txt
```

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

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 favorited, played, and watched content
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

👤 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)
Secure authentication with Trakt through device code flow
Personal data is fetched directly from your Trakt account

💬 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, favorited, played, watched, search, comments, ratings, watchlist) - pass page: int for single-page results with metadata (PaginatedResponse), or omit page to auto-fetch all results as a flat list

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

View all available resources

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/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/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

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

🛠️ Available Tools

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

Show Tools

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

# 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 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)

# 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)

Movie Tools

# 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 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 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)

Authentication & User Tools

# 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"}])

Check-in Tools

# 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!"
)

Comment Tools

# 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")

📝 Using with Claude

Once installed, Claude can use this MCP server to answer questions about entertainment data. Here are some examples to get you started.

"What shows are trending right now?"
"Show me the shows I've watched" (requires authentication)
"What's the rating for Game of Thrones?"

View more example questions

Public Data (No Authentication Required):

"Can you recommend some popular movies this week?"
"What are the most watched shows of the month?"
"Search for shows like 'Breaking Bad'"
"Search for movies like 'The Godfather'"
"Show me comments for Breaking Bad"
"What are people saying about The Godfather movie?"
"Show me comments for Season 1 of Stranger Things"
"Get comments for Season 2 Episode 5 of Game of Thrones"
"Show me comment #12345 with its replies"
"Show me comments for Breaking Bad but include spoilers"
"Show me the most liked comments for Breaking Bad"
"Get the highest rated comments for The Godfather movie"
"Show me the comments with most replies for Season 1 of Stranger Things"
"Show me the rating distribution for The Godfather"
"How highly rated is Breaking Bad?"
"Show me trailers for TRON: Legacy"
"Get videos for Game of Thrones"
"What trailers are available for The Godfather?"
"Get a detailed summary of Breaking Bad"
"Show me details about The Godfather movie"
"Give me basic info for Game of Thrones"

Personal Data (Requires Authentication):

"What was the last show I watched?"
"Show me the movies I've watched"
"What was the last movie I watched?"
"Show me my 10/10 rated movies"
"Add a 9/10 rating for Breaking Bad"
"Show me my watchlist"
"What movies are on my watchlist?"
"Add The Godfather to my watchlist"
"Add Breaking Bad to my watchlist with a note" (VIP)
"Remove The Dark Knight from my watchlist"
"Show me my watchlist sorted by when I added them"
"Check me in to Season 2 Episode 5 of Breaking Bad"
"Check me in to Season 1 Episode 3 of show ID 1388"

👤 Personal Data Access

With authentication, you can access:

Your complete watched show and movie history
Last watched dates for each show and movie
Number of times you've watched each show and movie
Check in to shows you're currently watching and track your progress
Personal viewing statistics
Your complete watchlist with filtering and sorting options
Add and remove items from your watchlist
Add personal notes to watchlist items (VIP feature)

All data is fetched directly from your Trakt account in real-time.

🔐 Authentication

The server uses Trakt's device authentication flow:

When you request user-specific data, the server will automatically initiate authentication if needed
You'll receive a code and a URL to visit on your browser
After entering the code on the Trakt website and authorizing the app, inform Claude that you've completed the authorization
Claude will check the authentication status and then fetch your personal data
Your authentication token is stored securely in auth_token.json for future requests

You can log out at any time using the clear_auth tool.

🐳 Docker Deployment

Using `docker run`

# Build the image (from project root, where the Dockerfile is located)
docker build -t trakt_mcpserver .

# Run the container using .env file
docker run -it --rm \
  --env-file .env \
  -p 8080:8080 \
  trakt_mcpserver

# Or run the container setting env variables
docker run -it --rm \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -p 8080:8080 \
  trakt_mcpserver

Using `docker compose`

# Builds the docker image and starts the service
docker compose up

This runs the server on http://localhost:8080 and proxies MCP requests over SSE (HTTP transport).

🧪 Development & Testing

For developers working with or extending this MCP server, here are testing tools and development workflows.

🚀 AI-Powered Development Experience

This project was built using AI-assisted development tools:

Cursor - AI-powered code editor for rapid development
Aider - AI pair programming tool for code collaboration
Claude Code - Claude's dedicated coding interface

Testing with MCP Inspector

Validate your MCP server implementation and explore available tools, resources, and prompts.

View MCP Inspector commands

# List available tools
npx @modelcontextprotocol/inspector --cli python server.py --method tools/list

# List available resources
npx @modelcontextprotocol/inspector --cli python server.py --method resources/list

# List available prompts
npx @modelcontextprotocol/inspector --cli python server.py --method prompts/list

Running Tests

Ensure code quality with pytest, type checking, and linting before making changes.

View test commands

# Install test dependencies
pip install -r requirements-dev.txt

# Run all tests
pytest

# Run with verbose output
pytest -v -s

# Type checking
pyright

# Code linting and formatting with ruff
ruff check --fix    # Auto-fix issues
ruff format         # Format code

📄 License

MIT License

Built with 🧠 AI and human collaboration

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

🖥️ An AI Experiment

📚 About MCP & Trakt

🚀 Quick Start

Docker Quickstart

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

Local Installation

Clone this repository

git clone https://github.com/yourusername/mcp-trakt.git
cd mcp-trakt

Install dependencies
```
pip install -r requirements.txt
```

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

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 favorited, played, and watched content
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

👤 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)
Secure authentication with Trakt through device code flow
Personal data is fetched directly from your Trakt account

💬 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, favorited, played, watched, search, comments, ratings, watchlist) - pass page: int for single-page results with metadata (PaginatedResponse), or omit page to auto-fetch all results as a flat list

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

View all available resources

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/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/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

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

🛠️ Available Tools

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

Show Tools

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

# 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 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)

# 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)

Movie Tools

# 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 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 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)

Authentication & User Tools

# 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"}])

Check-in Tools

# 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!"
)

Comment Tools

# 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")

📝 Using with Claude

Once installed, Claude can use this MCP server to answer questions about entertainment data. Here are some examples to get you started.

"What shows are trending right now?"
"Show me the shows I've watched" (requires authentication)
"What's the rating for Game of Thrones?"

View more example questions

Public Data (No Authentication Required):

"Can you recommend some popular movies this week?"
"What are the most watched shows of the month?"
"Search for shows like 'Breaking Bad'"
"Search for movies like 'The Godfather'"
"Show me comments for Breaking Bad"
"What are people saying about The Godfather movie?"
"Show me comments for Season 1 of Stranger Things"
"Get comments for Season 2 Episode 5 of Game of Thrones"
"Show me comment #12345 with its replies"
"Show me comments for Breaking Bad but include spoilers"
"Show me the most liked comments for Breaking Bad"
"Get the highest rated comments for The Godfather movie"
"Show me the comments with most replies for Season 1 of Stranger Things"
"Show me the rating distribution for The Godfather"
"How highly rated is Breaking Bad?"
"Show me trailers for TRON: Legacy"
"Get videos for Game of Thrones"
"What trailers are available for The Godfather?"
"Get a detailed summary of Breaking Bad"
"Show me details about The Godfather movie"
"Give me basic info for Game of Thrones"

Personal Data (Requires Authentication):

"What was the last show I watched?"
"Show me the movies I've watched"
"What was the last movie I watched?"
"Show me my 10/10 rated movies"
"Add a 9/10 rating for Breaking Bad"
"Show me my watchlist"
"What movies are on my watchlist?"
"Add The Godfather to my watchlist"
"Add Breaking Bad to my watchlist with a note" (VIP)
"Remove The Dark Knight from my watchlist"
"Show me my watchlist sorted by when I added them"
"Check me in to Season 2 Episode 5 of Breaking Bad"
"Check me in to Season 1 Episode 3 of show ID 1388"

👤 Personal Data Access

With authentication, you can access:

Your complete watched show and movie history
Last watched dates for each show and movie
Number of times you've watched each show and movie
Check in to shows you're currently watching and track your progress
Personal viewing statistics
Your complete watchlist with filtering and sorting options
Add and remove items from your watchlist
Add personal notes to watchlist items (VIP feature)

All data is fetched directly from your Trakt account in real-time.

🔐 Authentication

The server uses Trakt's device authentication flow:

When you request user-specific data, the server will automatically initiate authentication if needed
You'll receive a code and a URL to visit on your browser
After entering the code on the Trakt website and authorizing the app, inform Claude that you've completed the authorization
Claude will check the authentication status and then fetch your personal data
Your authentication token is stored securely in auth_token.json for future requests

You can log out at any time using the clear_auth tool.

🐳 Docker Deployment

Using `docker run`

# Build the image (from project root, where the Dockerfile is located)
docker build -t trakt_mcpserver .

# Run the container using .env file
docker run -it --rm \
  --env-file .env \
  -p 8080:8080 \
  trakt_mcpserver

# Or run the container setting env variables
docker run -it --rm \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -p 8080:8080 \
  trakt_mcpserver

Using `docker compose`

# Builds the docker image and starts the service
docker compose up

This runs the server on http://localhost:8080 and proxies MCP requests over SSE (HTTP transport).

🧪 Development & Testing

For developers working with or extending this MCP server, here are testing tools and development workflows.

🚀 AI-Powered Development Experience

This project was built using AI-assisted development tools:

Cursor - AI-powered code editor for rapid development
Aider - AI pair programming tool for code collaboration
Claude Code - Claude's dedicated coding interface

Testing with MCP Inspector

Validate your MCP server implementation and explore available tools, resources, and prompts.

View MCP Inspector commands

# List available tools
npx @modelcontextprotocol/inspector --cli python server.py --method tools/list

# List available resources
npx @modelcontextprotocol/inspector --cli python server.py --method resources/list

# List available prompts
npx @modelcontextprotocol/inspector --cli python server.py --method prompts/list

Running Tests

Ensure code quality with pytest, type checking, and linting before making changes.

View test commands

# Install test dependencies
pip install -r requirements-dev.txt

# Run all tests
pytest

# Run with verbose output
pytest -v -s

# Type checking
pyright

# Code linting and formatting with ruff
ruff check --fix    # Auto-fix issues
ruff format         # Format code

📄 License

MIT License

Built with 🧠 AI and human collaboration

Trakt

README Documentation

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

🖥️ An AI Experiment

📚 About MCP & Trakt

🚀 Quick Start

Docker Quickstart

Local Installation

Installing in Claude Desktop

✨ Features

🌎 Public Trakt Data

👤 Personal Trakt Data

💬 Comments & Reviews

🔄 General Features

🔥 Real-Time Trending Data

🔌 Available Resources

Show Resources

Movie Resources

User Resources

🛠️ Available Tools

📝 Using with Claude

👤 Personal Data Access

🔐 Authentication

🐳 Docker Deployment

Using docker run

Using docker compose

🧪 Development & Testing

🚀 AI-Powered Development Experience

Testing with MCP Inspector

Running Tests

📄 License

Quick Install

Quick Actions

Key Features

Trakt

README Documentation

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

🖥️ An AI Experiment

📚 About MCP & Trakt

🚀 Quick Start

Docker Quickstart

Local Installation

Installing in Claude Desktop

✨ Features

🌎 Public Trakt Data

👤 Personal Trakt Data

💬 Comments & Reviews

🔄 General Features

🔥 Real-Time Trending Data

🔌 Available Resources

Show Resources

Movie Resources

User Resources

🛠️ Available Tools

📝 Using with Claude

👤 Personal Data Access

🔐 Authentication

🐳 Docker Deployment

Using docker run

Using docker compose

🧪 Development & Testing

🚀 AI-Powered Development Experience

Testing with MCP Inspector

Running Tests

📄 License

Quick Install

Quick Actions

Key Features

Using `docker run`

Using `docker compose`

Using `docker run`

Using `docker compose`