Trakt MCP Server

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

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

Movies

Shows

Episodes

People

Calendar

History

Collection

Watched

Playback

Sync

Ratings

Watchlist

Checkin

Scrobble

Recommendations

User

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

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

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