trakt_mcpserver

🎬 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 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 - AI-powered code editor for rapid development
• Aider - AI pair programming tool for code collaboration
• Claude Code - Claude's dedicated coding interface
• Claude Opus - Architectural guidance and design decisions when needed

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

Movie Resources

User Resources

🛠️ 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)

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

# Search for movies by title to get movie IDs and details
search_movies(query="The Godfather", 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")

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

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
)

Comment Tools

# 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

   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

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

{
  "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

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

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