🎬 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, seasons, episodes, movies, people, 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_mcpserver \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -v trakt_auth:/data \
  -p 8080:8080 \
  ghcr.io/wwiens/trakt_mcpserver:latest

Run with uvx (no clone, no install)

Requires uv installed.

uvx --from git+https://github.com/wwiens/trakt_mcpserver trakt-mcp

Pin to a release tag for reproducibility:

uvx --from git+https://github.com/wwiens/[email protected] trakt-mcp

Claude Desktop / MCPhub configuration:

{
  "mcpServers": {
    "trakt": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wwiens/trakt_mcpserver",
        "trakt-mcp"
      ],
      "env": {
        "TRAKT_CLIENT_ID": "your_client_id",
        "TRAKT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Your Trakt OAuth token is persisted to ~/.trakt-mcp/auth_token.json (the directory is created on first login), so authorization survives across uvx invocations. To override the location — e.g. for Docker volumes or to keep multiple isolated accounts — set TRAKT_AUTH_TOKEN_PATH to an absolute path.

Local Installation

Requires Python 3.12 or newer.

1. Clone this repository

   git clone https://github.com/wwiens/trakt_mcpserver.git
   cd trakt_mcpserver
   

2. Create a virtual environment and install dependencies

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e .
   

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
   

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 anticipated, favorited, played, and watched content
• See the top-grossing U.S. box office movies from last weekend
• 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
• Browse show seasons with episode counts, aired episodes, and ratings per season
• Dive into specific seasons with detailed info, episode lists, ratings, cast & crew, videos, translations, and engagement stats
• See who’s watching a specific season right now
• Find lists containing a specific season
• Explore individual episodes with detailed summaries, ratings, cast & crew, videos, translations, and engagement stats
• See who’s watching a specific episode right now
• Find lists containing a specific episode
• Look up cast and crew for any movie or show, with optional guest stars for shows
• Explore people with biographies, social media, and full filmographies
• Browse a person’s credits across movies and shows with character names and episode counts
• Find lists containing a specific person

👤 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)
• Track show progress: See your watched progress for any TV show
  • View episodes watched vs aired with completion percentage
  • See your next episode to watch
  • View per-season breakdown with progress stats
  • Include hidden seasons and specials optionally
• Manage playback progress: View and clear paused playback items
  • See movies and episodes you paused mid-watch
  • View progress percentage and when you paused
  • Clear playback items you no longer need
• Manage watch history: Add and remove items from your history
  • Mark movies, shows, seasons, or episodes as watched
  • Optionally specify when you watched them
  • Remove items from your watch history
• Secure authentication with Trakt through device code flow
• Personal data is fetched directly from your Trakt account

🎯 Personalized Recommendations

• Get tailored movie and show suggestions based on your watch history and ratings (requires authentication)
• Filter out items you’ve already collected or watchlisted
• Hide recommendations you’re not interested in so they don’t come back
• Unhide previously hidden items to restore them

💬 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, anticipated, favorited, played, watched, search, comments, ratings, watchlist):
  • Pass page: int for single-page results with pagination metadata
  • Omit page to auto-paginate and return up to limit total items as a flat list
  • Use limit=0 to fetch all available results (capped at 100 for safety)

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

🛠️ Available Tools

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

📝 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?”

👤 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)
• Show progress tracking: See how far you are through any TV show, with next episode recommendations
• Playback progress: View and clear any movies or episodes you paused mid-watch
• Watch history management: Add or remove items from your watch history with optional timestamps

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 ~/.trakt-mcp/auth_token.json for future requests, with 0o600 permissions. Override the location with the TRAKT_AUTH_TOKEN_PATH env var; Docker images set it to /data/auth_token.json — mount a volume at /data (e.g. -v trakt_auth:/data) to persist auth across container recreations.

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

🐳 Docker Deployment

Two Docker images are available with different transport mechanisms. Each release also publishes a versioned tag (e.g. :0.9.0, :0.9.0-stdio) for pinning.

stdio Transport (MCPhub, Claude Desktop)

Use the :latest-stdio image (or pin a version like :0.9.0-stdio) for MCP clients that communicate via stdin/stdout:

# Pull and run the stdio image
docker run -i --rm --name trakt_mcpserver_stdio \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -v trakt_auth:/data \
  ghcr.io/wwiens/trakt_mcpserver:latest-stdio

Claude Desktop configuration:

{
  "mcpServers": {
    "trakt": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--name", "trakt_mcpserver_stdio",
        "-e", "TRAKT_CLIENT_ID=your_client_id",
        "-e", "TRAKT_CLIENT_SECRET=your_client_secret",
        "-v", "trakt_auth:/data",
        "ghcr.io/wwiens/trakt_mcpserver:latest-stdio"
      ]
    }
  }
}

SSE Transport (HTTP/Remote)

Use the :latest image for HTTP-based access:

# Option 1: Pull and run from GHCR (recommended)
docker run -d --rm --name trakt_mcpserver \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -v trakt_auth:/data \
  -p 8080:8080 \
  ghcr.io/wwiens/trakt_mcpserver:latest

# Option 2: Build locally and run
docker build -t trakt_mcpserver .
docker run -d --rm --name trakt_mcpserver \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -v trakt_auth:/data \
  -p 8080:8080 \
  trakt_mcpserver

Using docker compose

# Builds the docker image using the default Dockerfile (SSE variant) 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.

Running Tests

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

📄 License

MIT License

---