trakt-mcp

A lean, self-hosted MCP server that lets your AI assistant manage your Trakt watchlist and answer questions about your watch progress — from Claude on your phone, Claude Code, or any other MCP client.

"I just heard about Severance — put it on my watchlist." "How many episodes of Severance do I have left?"

It is deliberately not a wrapper around all of Trakt's 300+ endpoints. Ten focused tools keep the assistant's context small and its tool choices reliable.

Status: early (0.x), built for personal self-hosting. Provided as-is.

Tools

All tools carry MCP annotations (readOnlyHint, destructiveHint, …) so clients can ask for confirmation before changes.

Related MCP server: mcp-trakt

How sign-in works

The server is its own OAuth 2.1 authorization server (as the MCP spec requires for remote servers) and delegates the actual login to Trakt using Trakt's device flow: your AI app opens a page that shows a short code, you enter it at https://trakt.tv/activate, and the page continues by itself. The device flow needs no public redirect URL, so a Trakt development app is enough — which is what Trakt hands out to individuals.

• Owner passphrase. Every sign-in first asks for a passphrase that only you know (set once with trakt-mcp set-passphrase). Only after that does the server request a Trakt code. This binds the device flow to the person who started it: nobody can trick you into entering their code at trakt.tv/activate and get anything out of it.

• Allowlist. Only Trakt users listed in ALLOWED_TRAKT_USERS can obtain a token.

• Consent. The first time a client connects, you see a consent page naming it (after signing in with Trakt). Approval is bound to that client and your Trakt account.

• PKCE, single-use codes, rotating refresh tokens with replay detection, tokens stored only as SHA-256 hashes, 90-day maximum session. See SECURITY.md and docs/architecture.md.

Setup

1. Create a Trakt app

At https://app.trakt.tv/settings/apps create a Development app:

• Redirect URI: http://localhost:8000/trakt/callback (required by the form; the device flow does not use it, but Trakt expects a registered value on token refresh)

• JavaScript (CORS) origins: leave empty

• Permissions (/checkin, /scrobble): not needed

Note the Client ID (and the client secret, which is optional). As the app owner you can always sign in; add other people to the app's sign-in list on Trakt if needed.

2. Run it

cp .env.example .env   # fill in TRAKT_CLIENT_ID, PUBLIC_URL, ALLOWED_TRAKT_USERS
docker compose -f compose.example.yml up -d --build

Put it behind a TLS-terminating reverse proxy (see compose.example.yml for Caddy). The container needs no published port, runs as an unprivileged user, works with a read-only root filesystem and keeps its state in the /data volume (~50 MB RAM).

3. Connect your assistant

1. Set the owner passphrase once (at least 12 characters; keep it in your password manager): docker exec -it trakt-mcp trakt-mcp set-passphrase

2. Claude (web, desktop, Android, iOS): Settings → Connectors → Add custom connector, URL https://<your-host>/mcp, leave client ID/secret empty. Enter your passphrase, enter the code shown at trakt.tv/activate, then approve the consent page. The connector is then available in the mobile apps too. You sign in again after 90 days.

3. Claude Code: claude mcp add --transport http trakt https://<your-host>/mcp

4. Other MCP clients: add the client's OAuth callback URL to ALLOWED_REDIRECT_URIS.

Configuration

Development

uv sync
uv run pytest --cov          # tests (against an in-memory fake Trakt)
uv run ruff check src tests && uv run ruff format --check src tests
uv run mypy                  # strict
uv run bandit -c pyproject.toml -r src

Run locally: create a .env with PUBLIC_URL=http://localhost:8000, HOST=127.0.0.1 and DATA_DIR=./data, then uv run trakt-mcp.

License

MIT for the code.

The Trakt name and logo are trademarks of Trakt, Inc. The logo files in docs/assets/ are the unmodified downloads from the Trakt branding guidelines and are used only to refer to the service this project works with. Per those guidelines the Trakt logo is not used as this project's own logo or icon. This project is not affiliated with, sponsored or endorsed by Trakt.