Trakt MCP Server

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

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 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 to ~/.config/trakt.json. You never touch them again.

3. Add to your MCP client

No credentials needed in the config — the server reads them from ~/.config/trakt.json automatically.

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

Installation

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

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

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

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

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

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

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

Available Tools

Search

Movies

Shows

Episodes

People

Calendar

History

Ratings

Watchlist

Checkin

Recommendations

User

Total: 36 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 ~/.config/trakt.json — 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 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 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

• Never commit ~/.config/trakt.json or any file containing tokens to source control
• ~/.config/trakt.json is user-scoped and never read by MCP client configs
• 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.