Private Trakt MCP on Cloudflare

A single-owner ChatGPT connector for viewing history, TV progress, recommendations, watchlists, and ratings. Runs a pinned wwiens Trakt server behind the owner-only OAuth gateway adapted from the Intervals template.

GitHub OAuth verifies the exact numeric owner. ChatGPT receives separate gateway tokens with S256 PKCE, explicit browser-bound consent, audience checks, and refresh validation. Public discovery/registration never grants access to your data.

flowchart LR
  C[ChatGPT] -->|OAuth and MCP| W[Worker]
  W -->|Owner identity| G[GitHub OAuth]
  W --> K[OAuth KV]
  W --> D[Owner Durable Object]
  D --> P[Python Trakt container]
  P --> T[Trakt API]
  P -->|Private token bridge| D

The public template defaults to read-only (29 tools, including three account authorization tools). Private accessMode: track adds mark watched, add to watchlist, and save rating (32 tools). Writes require intentional user requests; marking history twice may create duplicate plays. Deletion, check-ins, scrobbling, and recommendation hiding are excluded at registration. Saving a rating may replace an existing rating. clear_auth disconnects Trakt; it does not delete viewing data.

Trakt tokens persist in Cloudflare Durable Object storage before login/refresh reports success. Container disk is never the source of truth. Container restarts retain authorization; an unfinished device-code flow must be restarted.

Setup

Set up with a coding agent

Fork or clone this template into your repository, then give the agent:

Follow AGENTS.md's end-to-end setup and resume runbook to deploy my own single-owner Trakt MCP server to my Cloudflare account. Automate the authorized checks, configuration and deployment; guide me through browser approvals and secure secret entry. Ask whether I want read-only or tracking mode. Complete Trakt device authorization and a real personal-data query, then report each acceptance result and any outstanding user-only checks.

The agent runbook covers fresh setup, interrupted provisioning and existing instances. The troubleshooting guide records the failures encountered in live setup and the verified fixes.

Prerequisites and local checks

Requires Node from .node-version, Docker with Linux amd64, Chrome/Chromium, and a Cloudflare Workers Paid account with Containers. Usage is billable; one named instance and ten-minute idle sleep are not a spending cap.

npm ci
npm run check:public
npm run check
REQUIRE_BROWSER_TESTS=true npm test
docker build --platform linux/amd64 -t trakt-mcp:test .
npm run test:container
npm run test:adapter
npm run build
npx cf deploy --prebuilt --mode production --dry-run

Copy deployment.json to ignored mode-0600 deployment.local.json. Fill your account, stable origin, verified numeric GitHub owner ID, GitHub OAuth Client ID, and Trakt Development app Client ID. Set accessMode to track for the three tracking tools. Keep deleteMode: none. TRAKT_DEPLOYMENT_FILE selects an alternative private settings file. No credentials or personal settings belong in the public template.

Follow deployment, including secure GitHub secret entry. Connect ChatGPT to PUBLIC_ORIGIN/mcp, choose OAuth, and leave client credentials blank when optional. Approve consent and GitHub login. Then ask the connector to start Trakt device authorization, approve the displayed code on Trakt, and ask it to check authorization status. Refresh tools after changes. Visible tools alone are not acceptance: execute a small personal history/progress query after Trakt approval. Current Trakt apps need no client secret; the required GitHub client secret belongs to a different authentication layer.

• Upstream comparison and decision

• Architecture and token trust boundary

• Authentication sequences: GitHub, Trakt device approval and token refresh

• Deployment and secure credentials

• Operations and acceptance

• Troubleshooting and verified setup fixes

• Validation status

Gateway: Apache-2.0. Trakt server: MIT; its notice is included in the image. Source commits and modifications are recorded in NOTICE.