Trakt

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

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