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. Build and run setup

npm install
npm run build
npm run 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": "node",
      "args": ["/path/to/mcp-trakt/dist/index.js"]
    }
  }
}

Installation

Run npm run setup first — this saves your credentials to ~/.config/trakt.json so no tokens are needed in any config file.

claude mcp add trakt node /path/to/mcp-trakt/dist/index.js

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

{
  "mcpServers": {
    "Trakt": {
      "command": "node",
      "args": ["/path/to/mcp-trakt/dist/index.js"]
    }
  }
}

Restart Claude Desktop after saving.

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "Trakt": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-trakt\\dist\\index.js"]
    }
  }
}

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

{
  "mcpServers": {
    "Trakt": {
      "command": "node",
      "args": ["/path/to/mcp-trakt/dist/index.js"]
    }
  }
}

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

{
  "mcpServers": {
    "Trakt": {
      "command": "node",
      "args": ["/path/to/mcp-trakt/dist/index.js"]
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "Trakt": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-trakt/dist/index.js"]
    }
  }
}

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.

Made with ❤️ for TV and movie fans

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