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. ## 🤖 What is MCP? Model Context Protocol (MCP) is an open specification that enables Large Language Models (LLMs) like Claude to interact with external systems and data sources. MCP creates a standardized way for AI models to: - Access real-time data beyond their training cutoff date - Connect to external APIs and web services through dedicated servers - Execute specialized tools and functions securely - Read from and write to external resources - Process complex data that would be difficult to handle in text-only formats At its core, MCP works by defining: 1. **Resources**: Structured data sources that an AI can read from or write to (like `trakt://shows/trending`) 2. **Tools**: Functions that the AI can invoke to perform specific actions (like `fetch_trending_shows`) 3. **Sessions**: Secure connections between the AI and MCP servers MCP servers like this one act as bridges between AI models and the external world, allowing them to be extended with new capabilities without requiring retraining. ## 📺 What is Trakt? [Trakt.tv](https://trakt.tv) is a platform that automatically tracks what TV shows and movies you watch. The service offers: - Comprehensive tracking of viewing habits across multiple streaming services - Social features to share and discuss what you're watching with friends - Personalized recommendations based on your viewing history - Extensive APIs that developers can use to build applications Trakt has become the standard for entertainment tracking with: - Over 14 million users tracking their viewing habits - Data on millions of movies and TV shows, including detailed metadata - Integration with popular media players and streaming services This MCP server taps into Trakt's rich API ecosystem to bring real-time entertainment data directly to your conversations with AI assistants like Claude. ## 🚀 AI-Powered Development Experience This project was developed using a combination of cutting-edge AI 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 This multi-tool approach demonstrates: - How AI-assisted development can dramatically accelerate building specialized MCP servers - The capabilities of modern AI in writing functional, well-structured code - A collaborative workflow between human intent and AI implementation - The power of using the right AI tool for each development phase ## ✨ 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) - Share check-ins to Twitter, Mastodon, or Tumblr - 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 - 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 ### 📺 Currently Trending Shows As of April 2025, you can access trending shows like: - "The White Lotus" (2021) - 7,870 watchers - "Daredevil: Born Again" (2025) - 6,738 watchers - "Severance" (2022) - 4,507 watchers ### 🎥 Currently Trending Movies The hottest movies right now: - "Black Bag" (2025) - 1,491 watchers - "A Working Man" (2025) - 1,226 watchers - "Mickey 17" (2025) - 764 watchers ## 🔌 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 ### Show Tools ```python # Get trending shows with optional limit parameter fetch_trending_shows(limit=10) # 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 by title to get show IDs and details search_shows(query="Breaking Bad", limit=5) # 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 by title to get movie IDs and details search_movies(query="The Godfather", limit=5) ``` ### Movie Tools ```python # Get trending movies with optional limit parameter fetch_trending_movies(limit=10) # 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 ```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"}]) ``` ### Check-in Tools ```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!", share_twitter=True, share_mastodon=False, share_tumblr=False ) ``` ### Comment Tools ```python # Get comments for a movie (sorted by newest by default) fetch_movie_comments(movie_id="123", limit=10, show_spoilers=False) # Get comments for a show sorted by most likes fetch_show_comments(show_id="456", limit=10, show_spoilers=False, sort="likes") # 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") ``` ## 🔐 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. ## 🚀 Setup 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: ``` TRAKT_CLIENT_ID=your_client_id TRAKT_CLIENT_SECRET=your_client_secret ``` 4. **Run the server** ```bash python server.py ``` ## 🐳 Run with Docker (SSE/HTTP mode) You can also deploy this MCP server using Docker with SSE (HTTP) transport. This runs the server on `http://localhost:8080` and proxies MCP requests over SSE. ### Option 1: 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 ``` ### Option 2: Using `docker compose` ```bash # Builds the docker image and starts the service docker compose up ``` ## 🧪 Development & Testing ### Testing with MCP Inspector ```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 ``` ### 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" } } } } ``` ### Running Tests ```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 ``` ## 📝 Using with Claude Once installed, you can ask Claude questions like: - "What shows are trending right now?" - "Can you recommend some popular movies this week?" - "What are the most watched shows of the month?" - "Show me the shows I've watched" (requires authentication) - "What was the last show I watched?" (requires authentication) - "Show me the movies I've watched" (requires authentication) - "What was the last movie I watched?" (requires authentication) - "Show me my 10/10 rated movies" (requires authentication) - "Add a 9/10 rating for Breaking Bad" (requires authentication) - "Search for shows like 'Breaking Bad'" - "Check me in to Season 2 Episode 5 of Breaking Bad" (uses title) - "Check me in to Season 1 Episode 3 of show ID 1388 and share it on Twitter" (uses ID) - "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" - "Search for movies like 'The Godfather'" - "Show me the most liked comments for Breaking Bad" (uses sort="likes") - "Get the highest rated comments for The Godfather movie" (uses sort="highest") - "Show me the comments with most replies for Season 1 of Stranger Things" (uses sort="replies") - "What's the rating for Game of Thrones?" - "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" (comprehensive data with air times, status, ratings) - "Show me details about The Godfather movie" (comprehensive data with production status, metadata) - "Give me basic info for Game of Thrones" (basic summary with title, year, ID only) Claude will use this MCP server to provide you with real-time data from Trakt. ## 👤 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 - Share your viewing activity on social media platforms All data is fetched directly from your Trakt account in real-time. ## 🔮 Future Development - Extending user authentication to access more personal data - Adding calendar events for upcoming episodes - Supporting scrobbling (tracking what you're watching) - Implementing recommendations based on watch history - Adding support for more social media platforms for sharing ## 📄 License [MIT License](LICENSE) --- <div align="center"> <p>Built with 🧠 AI and human collaboration</p> <p>Powered by Claude</p> </div>