VeilStrat

You can access real-time Trakt.tv entertainment data through an MCP server that bridges AI models with Trakt’s API, enabling precise queries, personal watch history, and interactive features like check-ins, ratings, and watchlists. This MCP server lets you fetch public Trakt data and your own authenticated data for tailored recommendations and conversations with your AI.

How to use

You interact with the server through an MCP-enabled client. Start by ensuring you have the correct transport (HTTP SSE or stdio) and valid Trakt credentials. Use the HTTP transport for remote access via a web client or remote MCP client, or use the stdio transport for local clients that communicate through standard input and output.

With authentication, you can access your personal Trakt data such as your watched history, ratings, and watchlist. You can also search for shows or films, fetch public data like trending content, and read comments or reviews. Use the available tools to fetch lists with optional pagination and to perform actions like adding items to your watchlist or check-ins to shows you are watching.

How to install

Prerequisites: you need Docker for containerized deployment or Python for local development. If you choose Docker, you’ll pull a prebuilt image. For local development, you’ll install Python dependencies and run the server script.

Option A: Docker Quickstart (HTTP transport)

docker run -d --rm --name trakt_mcpserver \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -p 8080:8080 \
  ghcr.io/wwiens/trakt_mcpserver:latest

This starts the server on http://localhost:8080 and exposes MCP requests over SSE (HTTP transport).

Option B: Local Installation (Python)

# 1) Clone the repository
git clone https://github.com/yourusername/mcp-trakt.git
cd mcp-trakt

# 2) Install dependencies
pip install -r requirements.txt

# 3) Set up environment with your Trakt credentials
cp .env.example .env
# Edit .env to add your credentials
# TRAKT_CLIENT_ID=your_client_id
# TRAKT_CLIENT_SECRET=your_client_secret

# 4) Run the server
python server.py

Additional installation paths

If you need to integrate with Claude Desktop, you can configure the MCP client to point to the server using a device with environment variables for the Trakt credentials. The configuration snippet shows how to wire the containerized server into Claude Desktop, using the standard MCP approach.

Configuration, security and getting started

Authentication uses Trakt’s device flow to securely authorize your account. Once authentication is requested, you receive a code and a URL to authorize on trakt.tv. After you complete authorization, you can query personal data and perform actions like rating content or updating your watchlist. Your authentication token is stored securely for subsequent requests.

Security best practices include keeping your credentials secret, rotating client credentials periodically, and logging out when you finish sessions on shared machines. You can log out at any time using the logout operation provided by the client.

Docker deployment and transport options

Two deployment transports are available. The http transport uses an SSE-based API over HTTP for remote access, while the stdio transport is designed for local MCP clients that communicate through standard input and output.

HTTP/Remote (latest image)

# Pull and run the HTTP transport image
docker run -d --rm --name trakt_mcpserver \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  -p 8080:8080 \
  ghcr.io/wwiens/trakt_mcpserver:latest

STDIO (local docker image)

# Run the stdio transport image for MCP clients like Claude Desktop
docker run -i --rm --name trakt_mcpserver_stdio \
  -e TRAKT_CLIENT_ID=your_client_id \
  -e TRAKT_CLIENT_SECRET=your_client_secret \
  ghcr.io/wwiens/trakt_mcpserver:stdio

Claude Desktop configuration can point to either transport by using the appropriate command and environment variables within the client’s MCP configuration.

Notes and examples

Public data endpoints provide trending, popular, and watched content with real-time metrics. Personal data endpoints let you retrieve your watched shows, watch history, and your watchlist, including options to filter, sort, paginate, and add optional notes to watchlist items. Check-in features let you mark episodes or seasons as watched and include custom messages.

Examples of supported prompts include asking for trending shows, retrieving your watched list, or requesting details about a specific title, such as its summary, ratings, or videos.

Troubleshooting and testing

If you encounter authentication issues, ensure your TRAKT_CLIENT_ID and TRAKT_CLIENT_SECRET are correctly configured and that device authorization completed successfully on trakt.tv. Use the logout operation to reset tokens if needed.

Development and testing can be aided by MCP Inspector and a local test setup, including unit tests and type checks. Use the provided tooling to list available tools, resources, and prompts for troubleshooting and exploration.

Security notes

Personal data is fetched directly from your Trakt account in real time. Always ensure you are operating within trusted environments and secure networks to protect access tokens.

Available tools

start_device_auth

Initiate the device authorization flow with Trakt to authenticate a user.

check_auth_status

Check the status of an ongoing authentication flow.

clear_auth

Clear stored authentication tokens and log out.

fetch_user_watched_shows

Fetch shows watched by the authenticated user with optional limit.

fetch_user_watched_movies

Fetch movies watched by the authenticated user with optional limit.

fetch_user_ratings

Fetch the authenticated user ratings with pagination.

add_user_ratings

Add ratings for movies, shows, seasons, or episodes.

remove_user_ratings

Remove existing ratings by their IDs.

fetch_user_watchlist

Fetch the authenticated user watchlist with pagination and sorting.

add_user_watchlist

Add items to the user watchlist with optional notes.

remove_user_watchlist

Remove items from the user watchlist.

checkin_to_show

Check in to a show episode by ID or by title with an optional message.

search_shows

Search for shows with pagination metadata and automatic pagination.

fetch_show_summary

Get a comprehensive or basic summary for a show by ID.

fetch_show_videos

Fetch videos for a show, with optional markdown embedding.

fetch_show_ratings

Get ratings for a show by ID.

fetch_show_comments

Retrieve comments for a show, with options for spoilers and sorting.

fetch_comment

Fetch a specific comment by ID.

fetch_comment_replies

Get replies for a specific comment.

fetch_movie_comments

Retrieve comments for a movie, with spoiler options and pagination.

fetch_movie_ratings

Get ratings for a movie by ID.

fetch_movie_summary

Get a comprehensive or basic summary for a movie by ID.

fetch_movie_videos

Fetch videos for a movie, with optional markdown embedding.

search_movies

Search for movies with automatic pagination and optional pages.

fetch_trending_shows

Get trending shows with optional pagination and limits.

fetch_trending_movies

Get trending movies with optional pagination and limits.