> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/mdblist.md).

# MDBList

{% tabs %}
{% tab title="End users" %}

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2FWJkUuJcWMFP559gaLY7m%2Fimage.png?alt=media&amp;token=fea8ea24-3f9b-4dbd-b07d-a942ec0772d4" alt=""><figcaption></figcaption></figure>

Connect MDBList to synchronize supported lists and activity with CrossWatch.

{% hint style="info" %}
Use **Device Code** for new setups. It is the default and recommended auth mode.

**API key** auth still works as a fallback.
{% endhint %}

### What CrossWatch can sync

**Read** brings data into CrossWatch; **Write** sends changes to this provider.

| Feature    | Read | Write | Notes                                                          |
| ---------- | ---- | ----- | -------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Movies and shows.                                              |
| History    | Yes  | Yes   | Movies, shows, seasons and episodes.                           |
| Ratings    | Yes  | Yes   | Movies, shows, seasons and episodes.                           |
| Progress   | Yes  | Yes   | Resume positions for movies and episodes.                      |
| Playlists  | Yes  | Yes   | Manual lists are writable; smart lists are read-only.          |
| Collection | Yes  | Yes   | Movies, shows, seasons and episodes, with optional media info. |

**Live scrobbling:** Scrobble destination; cannot be a Watcher source.

See the [synchronization guide](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/mdblist.md) for matching rules and feature restrictions.

### Connect MDBList with Device Code

1. Open **Settings → Connections**.
2. Set **Authentication Method** to **Device Code**.
3. Click **Connect MDBList**.
4. A browser window opens so you can enter your code.
5. Copy the **Link code (PIN)** from CrossWatch.
6. Paste the code into MDBList.
7. Wait until CrossWatch shows **Connected with Device Code**.

### Use the legacy API key mode

1. Open <https://mdblist.com/preferences/#api>
2. Create or copy your MDBList API key.
3. In CrossWatch, set **Authentication Method** to **API key**.
4. Paste the API key into CrossWatch.
5. Click **Connect MDBList**.

### Account and API quota

Hover over the MDBList provider status to see **Account**, **Plan**, **API calls left today** and **Resets**, when MDBList supplies them. The reset time uses your display date/time settings. A remaining count of `0` means the daily quota is exhausted. Missing or expired quota information is hidden; a blank quota is not an unlimited allowance.

### Troubleshooting

* If the auth window does not open, disable popup blockers for CrossWatch.
* If the link code fails, click **Connect MDBList** again to generate a new code.
* If you use API key mode and auth fails, regenerate the key and reconnect.
* If writes fail, verify items have stable IDs (TMDb/IMDb) in the source provider.
* If you see `429 Too Many Requests`, check the quota and reset time. Wait for the quota to reset if exhausted; reduce request frequency if you are hitting short-term limits.\
  Guide: [Provider rate limiting](https://wiki.crosswatch.app/crosswatch/advanced-and-api/rate-limiting-and-retries.md).
  {% endtab %}

{% tab title="Power users" %}

## Power users

### Auth modes

* `Device Code` — recommended
* `API key` — legacy fallback

### Config keys

Stored under:

* `mdblist.rate_limit.get_per_sec`, `mdblist.rate_limit.post_per_sec`
* `mdblist.api_key` when you use legacy API key auth

CrossWatch stores the MDBList token automatically when you use Device Code auth.

Rate-limit defaults and tuning: [Provider rate limiting](https://wiki.crosswatch.app/crosswatch/advanced-and-api/rate-limiting-and-retries.md)

### Related docs

* Sync module: [MDBList module](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/mdblist.md)
* Adapter: [Adapter: MDBList](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/mdblist.md)
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/mdblist.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
