████████╗██████╗  █████╗ ██╗  ██╗████████╗
╚══██╔══╝██╔══██╗██╔══██╗██║ ██╔╝╚══██╔══╝
   ██║   ██████╔╝███████║█████╔╝    ██║
   ██║   ██╔══██╗██╔══██║██╔═██╗    ██║
   ██║   ██║  ██║██║  ██║██║  ██╗   ██║
   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝  ╚═╝

A Trakt MCP server with 36 tools for TV show and movie tracking, sync, ratings, watchlists, and checkins.

Features • Quick Start • Installation • Tools • Development

Features

• 🔍 Search movies, shows, episodes, and people across Trakt's database
• 🎬 Movies — details, trending, popular, related, ratings, and cast
• 📺 Shows & Episodes — full show info, seasons, episode details, cast
• 👤 People — actor/director profiles and filmographies
• 📅 Calendar — your personalised upcoming episodes and movies
• 🕐 History — view, add, and remove watch history entries
• ⭐ Ratings — get, add, and remove ratings for movies, shows, and episodes
• 📋 Watchlist — full CRUD on your movie/show watchlist
• ✅ Checkin — check into what you're watching right now
• 🤖 Recommendations — personalised movie and show suggestions

Quick Start

1. Create a Trakt API app

Go to trakt.tv/oauth/applications/new and create a new app. You only need to fill in the name — leave the redirect URI as urn:ietf:wg:oauth:2.0:oob. Copy your Client ID and Client Secret.

2. Run setup

npx @kud/mcp-trakt@latest setup

This launches the device OAuth flow: paste your Client ID and Secret when prompted, visit the URL shown, enter the code, and your credentials are saved securely to macOS Keychain. You never touch them again.

3. Add to your MCP client

No credentials needed in the config — the server reads them from macOS Keychain automatically.

{
  "mcpServers": {
    "Trakt": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-trakt@latest"]
    }
  }
}

Installation

Run npx @kud/mcp-trakt@latest setup first — this saves your credentials to macOS Keychain so no tokens are needed in any config file.

claude mcp add trakt npx -- -y @kud/mcp-trakt@latest

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "Trakt": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-trakt@latest"]
    }
  }
}

Restart Claude Desktop after saving.

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "Trakt": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-trakt@latest"]
    }
  }
}

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "Trakt": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-trakt@latest"]
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "Trakt": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-trakt@latest"]
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "Trakt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kud/mcp-trakt@latest"]
    }
  }
}

Available Tools

Search

| Tool | Description | | -------- | ---------------------------------------------------- | | search | Search for movies, shows, episodes, people, or lists |

Movies

| Tool | Description | | ------------------------ | --------------------------------------------------- | | get_movie | Get detailed information about a movie | | get_trending_movies | Movies currently being watched across Trakt | | get_popular_movies | Most popular movies on Trakt | | get_anticipated_movies | Most anticipated movies based on watchlist activity | | get_boxoffice_movies | Top 10 weekend box office movies | | get_movie_ratings | Community rating distribution for a movie | | get_movie_related | Movies related to a given movie | | get_movie_people | Cast and crew for a movie |

Shows

| Tool | Description | | ----------------------- | -------------------------------------------------- | | get_show | Get detailed information about a TV show | | get_trending_shows | Shows currently being watched across Trakt | | get_popular_shows | Most popular TV shows on Trakt | | get_anticipated_shows | Most anticipated shows based on watchlist activity | | get_show_ratings | Community rating distribution for a show | | get_show_seasons | All seasons, optionally with full episode details | | get_show_people | Cast and crew for a show | | get_show_related | TV shows related to a given show |

Episodes

| Tool | Description | | --------------------- | ----------------------------------- | | get_season_episodes | All episodes in a specific season | | get_episode | Full details for a specific episode |

People

| Tool | Description | | -------------------- | ---------------------------------- | | get_person | Actor or director profile | | get_person_credits | Movie or show credits for a person |

Calendar

| Tool | Description | | ------------------------ | -------------------------------------------- | | get_my_show_calendar | My upcoming episodes (personalised) | | get_my_movie_calendar | My upcoming movies (personalised) | | get_all_show_calendar | All shows premiering and airing across Trakt | | get_all_movie_calendar | All movies releasing across Trakt |

History

| Tool | Description | | --------------------- | ---------------------------------------- | | get_history | Watch history for the authenticated user | | add_to_history | Mark movies or episodes as watched | | remove_from_history | Remove entries from watch history |

Collection

| Tool | Description | | ------------------------ | ----------------------------------- | | get_collection_movies | All movies in the user's collection | | get_collection_shows | All shows in the user's collection | | add_to_collection | Add movies, shows, or episodes | | remove_from_collection | Remove items from the collection |

Watched

| Tool | Description | | -------------------- | ---------------------------------------------- | | get_watched_movies | All watched movies with play counts | | get_watched_shows | All watched shows with play counts per episode |

Playback

| Tool | Description | | ----------------- | ---------------------------------------- | | get_playback | Paused playback progress to resume later | | delete_playback | Delete a paused playback entry |

Sync

| Tool | Description | | -------------------------- | -------------------------------------------------- | | get_sync_last_activities | Timestamps for when each resource was last updated |

Ratings

| Tool | Description | | --------------- | ----------------------------------------------- | | get_ratings | Ratings given by the authenticated user | | add_rating | Rate movies, shows, seasons, or episodes (1–10) | | remove_rating | Remove ratings from items |

Watchlist

| Tool | Description | | ----------------------- | --------------------------------------- | | get_watchlist | View the authenticated user's watchlist | | add_to_watchlist | Add movies, shows, or episodes | | remove_from_watchlist | Remove items from the watchlist |

Checkin

| Tool | Description | | ---------------- | -------------------------------------------------- | | checkin | Check in to a movie or episode you're watching now | | delete_checkin | Cancel the current active checkin |

Scrobble

| Tool | Description | | ---------------- | ---------------------------------------------------- | | scrobble_start | Start scrobbling when playback begins | | scrobble_pause | Pause scrobbling to save progress | | scrobble_stop | Stop scrobbling when playback ends to record a watch |

Recommendations

| Tool | Description | | --------------------------- | ------------------------------------ | | get_movie_recommendations | Personalised movie recommendations | | get_show_recommendations | Personalised TV show recommendations |

User

| Tool | Description | | ------------------- | --------------------------------------- | | get_user_profile | Profile info for any user (or yourself) | | get_user_stats | Watch statistics for a user | | get_user_watching | What a user is currently watching |

Total: 53 Tools

Example Conversations

"What movies are trending on Trakt right now?"

"Search for Breaking Bad and give me its full details."

"What episodes of Severance do I have coming up this week?"

"Mark that I just watched Dune: Part Two — give it a 9."

"Add The Penguin to my watchlist."

"Check me in to S02E01 of The Bear."

"What have I watched this month?"

"Give me 10 personalised movie recommendations."

"Who plays the lead in Succession and what else have they been in?"

"What are my all-time watch stats?"

Development

Project Structure

mcp-trakt/
├── src/
│   └── index.ts       # Full server — all 36 tools
├── dist/              # Compiled output (git-ignored)
├── setup.js           # OAuth device flow setup script
├── package.json
└── tsconfig.json

Scripts

| Script | Purpose | | --------------------- | ------------------------------------------ | | npm run setup | Run OAuth device flow and save credentials | | npm run build | Compile TypeScript to dist/ | | npm run build:watch | Watch mode compilation | | npm run dev | Run directly with tsx (no build needed) | | npm run inspect | Open MCP Inspector against built output | | npm run inspect:dev | Open MCP Inspector with live tsx | | npm run typecheck | Type-check without emitting | | npm run clean | Remove dist/ |

Dev Workflow

# Run without building
npm run dev

# Inspect all tools interactively in the browser
npm run inspect:dev

Authentication

Trakt uses OAuth 2.0. The npm run setup script handles the full device flow — you never manage tokens manually.

How it works

1. Run npm run setup
2. Enter your Client ID and Client Secret from trakt.tv/oauth/applications
3. Visit the URL shown (e.g. https://trakt.tv/activate), enter the displayed code
4. Tokens are saved to macOS Keychain — the server reads them automatically on every start

To refresh an expired token, just run npm run setup again.

Test your credentials

curl -s https://api.trakt.tv/users/me \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: YOUR_CLIENT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" | jq .username

Troubleshooting

Server not showing in Claude Desktop

• Check JSON syntax in claude_desktop_config.json
• Verify the path to dist/index.js is absolute and the file exists
• Run npm run build if dist/ is missing

401 / auth errors

• Access tokens expire after 3 months — regenerate via the OAuth device flow
• Make sure MCP_TRAKT_CLIENT_ID matches the app your access token was issued for
• Check logs: Claude Desktop → Help → Show Logs

No data returned for personal endpoints (history, watchlist, etc.)

• These require a valid MCP_TRAKT_ACCESS_TOKEN — public/read-only client_id alone is not enough
• Make sure the token was granted the correct scopes during the OAuth flow

Security Best Practices

• Credentials are stored in macOS Keychain — never in plain files or config
• Rotate your access token if it is accidentally exposed — run npm run setup again
• Trakt access tokens expire after 90 days — re-run npm run setup to refresh
• Treat your access token like a password: full account access with history/checkin write rights

Tech Stack

| | | | ------------- | ------------------------------------ | | Runtime | Node.js ≥ 20 | | Language | TypeScript 5.x | | Target | ES2023 | | Protocol | Model Context Protocol (MCP) SDK 1.x | | HTTP Client | Native fetch | | Module System | ESM ("type": "module") |

Contributing

Issues and PRs welcome at github.com/kud/mcp-trakt.

License

MIT © kud

Acknowledgments

Built on the Model Context Protocol SDK by Anthropic. API provided by Trakt.

Support

Open an issue at github.com/kud/mcp-trakt/issues.

Made with ❤️ for TV and movie fans

⭐ Star this repo if it's useful • ↑ Back to top