🔐 Authentication

Set up Trakt OAuth via the device flow — tokens are saved to the macOS Keychain, never to config files.

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

⚙️ How it works

Run npm run setup
Enter your Client ID and Client Secret from trakt.tv/oauth/applications
Visit the URL shown (e.g. https://trakt.tv/activate), enter the displayed code
Tokens are saved to the 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

🛡️ Security best practices

Credentials are stored in the 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

🧰 Tools

The full reference for all 53 Trakt tools, grouped by category.

🩺 Troubleshooting

Common issues with mcp-trakt — server not showing, auth errors, and empty personal data.

On this page

⚙️ How it works 🧪 Test your credentials 🛡️ Security best practices