Your Trakt.
Your favorite client

Terminal & desktop Code

Claude Code

Install from the marketplace

Run these commands in your terminal:

claude plugin marketplace add swack-tools/trakt-ai-plugin
claude plugin install trakt-mcp@trakt-mcp

Start a new Claude Code session. Open /mcp, select the plugin’s Trakt server, and authenticate. Complete the device-code walkthrough below.

In the Claude desktop app’s local Code sessions, use + → Plugins → Add plugin after adding the marketplace. User-scoped command-line tool installs are also available to local desktop Code sessions on the same computer. Hosted sessions have different plugin availability.

Or add the server directly

claude mcp add --transport http trakt https://trakt.swacktech.com/mcp

Open /mcp in Claude Code to authenticate. The command defaults to the local project scope; add --scope user if you want the direct server available across projects.

Update the plugin

claude plugin marketplace update trakt-mcp
claude plugin update trakt-mcp@trakt-mcp

Start a new session after updating.

Official guidance: Claude Code plugin installation and scopes.

Desktop & Claude web

Claude desktop and web

Install the repository marketplace

1. Open Customize → Plugins in Claude desktop or claude.ai.
2. Choose Add → Add marketplace, then enter https://github.com/swack-tools/trakt-ai-plugin.
3. Select Trakt MCP and add it to your account.
4. Open the plugin’s Connectors tab. Add its Trakt connector if needed, then choose Connect and complete authentication.

Some desktop versions label this route Settings → Plugins → Add → Add Marketplace → Add from a repository. Follow the available repository import flow. Organization policies can restrict marketplace sources and require an owner to add connectors.

Or add a custom remote connector

1. Open Customize → Connectors and choose + → Add custom connector.
2. Name it Trakt and enter https://trakt.swacktech.com/mcp.
3. Add it and select Connect. Use the browser/device-code flow below.
4. Enable the connector for the conversation through + → Connectors.

For Team or Enterprise, an owner first adds the custom web connector under Organization settings → Connectors; each member then connects their own Trakt account. Remote connectors use your Claude account and are separate from local desktop JSON configuration.

Official guidance: Claude plugins and custom remote connectors.

Terminal

Codex command-line tool

Install from the marketplace

codex plugin marketplace add swack-tools/trakt-ai-plugin
codex plugin add trakt-mcp@trakt-mcp

Start a new Codex session, open /mcp, and follow the authentication prompt for the plugin’s Trakt server. The commands described earlier are available in Codex command-line tool 0.157.1; run codex plugin --help to check your installation.

Or add the server directly

codex mcp add trakt --url https://trakt.swacktech.com/mcp
codex mcp login trakt

If adding the server already completed login, a second login is unnecessary. Approve access in the browser, then verify the connection with /mcp in a new session.

Update the plugin

codex plugin marketplace upgrade trakt-mcp
codex plugin add trakt-mcp@trakt-mcp

Start a new session after updating.

Official guidance: repository marketplaces and Codex MCP configuration. Command-line tool command syntax checked locally with --help.

Local desktop client

Codex desktop

Add the marketplace with the Codex command-line tool commands described earlier on the same host. Open the desktop plugin browser, select the trakt-mcp marketplace, and install Trakt MCP if it is not already installed. Restart the app or start a new chat to load the connection, then authenticate when prompted.

For direct MCP setup, open Settings → MCP servers → Add server. Name the server trakt, choose Streamable HTTP, and enter https://trakt.swacktech.com/mcp. Save, restart the connection, and select Authenticate.

The local desktop client, Codex command-line tool, and IDE extension share MCP configuration on the same Codex host. Running the direct command-line tool setup is also a way to configure that desktop connection. A local setup does not configure ChatGPT web.

Official guidance: desktop MCP setup and shared configuration. Current OpenAI documentation also describes Codex inside the ChatGPT desktop app; labels may vary by app version.

Hosted conversations

ChatGPT web

ChatGPT web does not read your local Codex configuration or install a repository just because you added it with the Codex command-line tool. Connect the hosted MCP server as a personal plugin using developer mode, where your account and workspace permit it.

1. In ChatGPT, open Settings → Security and login and enable Developer mode.
2. Open Plugins, select the plus button, and enter https://trakt.swacktech.com/mcp as the server URL.
3. Use OAuth for authentication. Complete the connection prompts and approve your Trakt account using the device code.
4. Open your personal plugins and install the connection.
5. Start a new Work chat, type @, select your Trakt plugin, and ask for watched history or recommendations.

Older account interfaces may use Apps or Connectors labels. Workspace administrators control which connections and tools are available. If developer mode or custom connections are unavailable, use a supported local client or the OpenAPI Actions integration where available.

This creates a personal MCP connection. It does not publish Trakt MCP to OpenAI’s public plugin directory. OpenAPI Actions are a separate OAuth/API integration.

Official guidance: connect a personal MCP plugin and local MCP versus hosted web tools.

Use the parts you need

Install skills separately

The complete plugin is the simplest option. To use individual workflows, obtain the repository or a reviewed release artifact and copy the chosen plugins/trakt-mcp/skills/<name>/ folder intact, including its SKILL.md and any bundled references.

Choose what-to-watch, watching-profile, find-title, lists-and-watchlist, upcoming-releases, manage-library, or connection-help. Preserve an existing same-named skill instead of overwriting it silently. Start a new session after installation. A skill does not install or authenticate the server, and a standalone MCP server does not automatically load these skills.

For a local checkout, python3 scripts/package_plugin.py produces plugin and individual skills ZIPs under ignored dist/submission/. There is no published release artifact until the owner reviews and publishes one. See workflow examples and platform limits.

One-time account approval

Sign in with a device code

1. Start authentication in your client. The Trakt MCP browser page shows which client is requesting access and whether it requests reads and writes.
2. Choose Connect Trakt. The page displays a short activation code.
3. Open trakt.tv/activate. Sign in to your own Trakt account, enter the displayed code, and approve access.
4. Return to the connection page. It completes authorization automatically and returns control to your client.
5. Try a read. Ask: Show my watched movies using Trakt. An installed plugin still needs this account authorization before personalized tools work.

Each person authorizes their own account. No shared Trakt login, operator API keys, or manually pasted bearer tokens are needed for the normal MCP login. Public OAuth clients use dynamic registration and S256 PKCE.

Read and write permission

New browser OAuth connections request trakt:read trakt:write when scope is omitted, and the consent page states the requested access. Clients that explicitly request only trakt:read remain read-only. The write tool requires both write permission and a concrete change that you requested.

Existing connection tokens and standalone device login remain read-only. Reauthorize the server through your client's OAuth controls with trakt:read trakt:write to enable writes. Token refresh preserves the original scope. Reconnecting upstream Trakt with the device tools does not elevate the client's permission. There is no need to change credentials manually or test access with a mutation.

For a standalone Codex server named trakt, request the two scopes explicitly:

codex mcp login trakt --scopes trakt:read,trakt:write

Complete the browser consent and device-code flow, then start a new session. For a plugin-managed connection, use its authentication controls and the server name shown by /mcp.

If something doesn’t connect

The code expired or approval was denied

Start authentication again to get a fresh code. Use the code from the current connection page.

The server is installed but tools are missing

Start a new session, check that the plugin/connector is enabled, and finish its OAuth login. Check /mcp in local command-line tool clients.

Opening /mcp in a browser returns 405

This is expected: Streamable HTTP uses POST. Add the URL to an MCP client; it is not a web dashboard.

A client only supports SSE

Use https://trakt.swacktech.com/sse. Reconnect and initialize after disconnection; events are not replayed.

The marketplace isn’t visible

Refresh its catalog, verify the client supports repository marketplaces, and check organization policy. The direct remote MCP connection is an alternative.

A write returns write_authorization_required

Reauthorize the server in your client with read and write scope. Refreshing the existing token cannot grant new permission.

A write timed out

Read the target state before considering another attempt. The change might already have reached Trakt; repeating it can duplicate events.

Disconnecting

Remove or turn off the connection in your client. To erase the service-side connection and stored tokens, use authenticated DELETE /auth/session. Revoke the app in Trakt settings to revoke Trakt-side authorization too.

Full API status codes, token lifecycle, and operational limits →