Trakt

# 🎬 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)](https://modelcontextprotocol.io/) enables AI models to interact with external systems through standardized tools and resources. [Trakt.tv](https://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 ```bash 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 1. **Clone this repository** ```bash git clone https://github.com/yourusername/mcp-trakt.git cd mcp-trakt ``` 2. **Install dependencies** ```bash pip install -r requirements.txt ``` 3. **Set up your environment** ```bash cp .env.example .env ``` Then edit `.env` to add your Trakt API credentials: ```bash TRAKT_CLIENT_ID=your_client_id TRAKT_CLIENT_SECRET=your_client_secret ``` 4. **Run the server** ```bash python server.py ``` ### Installing in Claude Desktop Add to your Claude Desktop MCP configuration file: ```json { "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. <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/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 | </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 # 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) ``` </details> <details> <summary><strong>Movie Tools</strong></summary> ```python # 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) ``` </details> <details> <summary><strong>Authentication & User Tools</strong></summary> ```python # 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"}]) ``` </details> <details> <summary><strong>Check-in Tools</strong></summary> ```python # 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!" ) ``` </details> <details> <summary><strong>Comment Tools</strong></summary> ```python # 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") ``` </details> ## 📝 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?" <details> <summary><strong>View more example questions</strong></summary> **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" </details> ## 👤 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: 1. When you request user-specific data, the server will automatically initiate authentication if needed 2. You'll receive a code and a URL to visit on your browser 3. After entering the code on the Trakt website and authorizing the app, inform Claude that you've completed the authorization 4. Claude will check the authentication status and then fetch your personal data 5. 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` ```bash # 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` ```bash # 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](https://cursor.sh/)** - AI-powered code editor for rapid development - **[Aider](https://aider.chat/)** - AI pair programming tool for code collaboration - **[Claude Code](https://claude.ai/code)** - Claude's dedicated coding interface ### Testing with MCP Inspector Validate your MCP server implementation and explore available tools, resources, and prompts. <details> <summary><strong>View MCP Inspector commands</strong></summary> ```bash # 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 ``` </details> ### Running Tests Ensure code quality with pytest, type checking, and linting before making changes. <details> <summary><strong>View test commands</strong></summary> ```bash # 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 ``` </details> ## 📄 License [MIT License](LICENSE) --- <div align="center"> <p>Built with 🧠 AI and human collaboration</p> <p>Powered by Claude</p> </div>