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

🖥️ 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 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.

🚀 The Cursor Development Experience

This entire project was developed using Cursor, a code editor built for the AI era, with Claude 3.7 Sonnet generating all code. This 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

✨ 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

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

🔄 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

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

Movie Tools

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

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

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!",
    share_twitter=True,
    share_mastodon=False,
    share_tumblr=False
)

🔐 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 for future requests

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

🚀 Setup

1. Clone this repository

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

2. Install dependencies

   pip install -r requirements.txt
   

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
   

🧪 Development & Testing

Testing with MCP Inspector

mcp dev server.py

Installing in Claude Desktop

mcp install server.py

📝 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)
• "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)

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
• Extending search to include movies in addition to shows
• Adding support for more social media platforms for sharing

📄 License

MIT License

---

<div align="center"> <p>Built with 🧠 AI and human collaboration</p> <p>Powered by Cursor + Claude 3.7 Sonnet</p> </div>