Trakt MCP server

MCP Trakt is a Model Context Protocol server that bridges AI language models with the Trakt.tv API, allowing access to real-time entertainment data and personal viewing history. This server enables AI assistants to retrieve trending shows and movies, access user watch history, and interact with comments and ratings from the Trakt community.

Installation

Follow these steps to set up your own MCP Trakt server:

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. Configure environment variables

   cp .env.example .env
   

   Edit the .env file 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
   

Authentication

The server uses Trakt's device authentication flow:

1. When requesting user-specific data, the server automatically initiates authentication if needed
2. You'll receive a code and a URL to visit in your browser
3. After entering the code on the Trakt website and authorizing the app, tell your AI assistant that you've completed authorization
4. The AI will check authentication status and fetch your personal data
5. Your authentication token is stored securely in auth_token.json for future requests

You can log out anytime using the clear_auth tool.

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)

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

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

# Search for movies by title to get movie IDs and details
search_movies(query="The Godfather", limit=5)

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

Integrating with Claude

Once the server is running, you can configure Claude Desktop to use it by adding to your 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"
      }
    }
  }
}

Example Usage Queries

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)
• "Search for shows like 'Breaking Bad'"
• "Check me in to Season 2 Episode 5 of Breaking Bad"
• "Show me comments for Breaking Bad"
• "What are people saying about The Godfather movie?"
• "Show me comments for Season 1 of Stranger Things"
• "Get the highest rated comments for The Godfather movie"
• "What's the rating for Game of Thrones?"
• "Show me the rating distribution for The Godfather"

Testing the Server

You can test the server using the 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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "trakt" '{"command":"python","args":["server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "trakt": {
            "command": "python",
            "args": [
                "server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "trakt": {
            "command": "python",
            "args": [
                "server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect