> For the complete documentation index, see [llms.txt](https://dinproxy.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dinproxy.gitbook.io/docs/guides/web-unlocker/mcp-and-cli.md).

# MCP & CLI

Use the Web Unlocker from AI assistants (MCP) and from the command line.

Besides the [API](https://dinproxy.gitbook.io/docs/guides/web-unlocker/api-reference.md) and [proxy mode](https://dinproxy.gitbook.io/docs/guides/web-unlocker/proxy-mode.md), the Web Unlocker has two ready-made ways in. Both sign in with a [proxy user](https://dinproxy.gitbook.io/docs/getting-started/proxy-users.md) and are billed like the API: **1 result per successful page**, failed pages are free.

On the dashboard, **Products → Web Unlocker → Connect your tools** shows every setting below already filled in for the proxy user you choose.

## MCP server for AI assistants

The Web Unlocker is an [MCP](https://modelcontextprotocol.io) server, so AI assistants such as Cursor, Claude and VS Code can fetch pages for you while they work.

| Setting    | Value                                                                   |
| ---------- | ----------------------------------------------------------------------- |
| Server URL | `https://app.dinproxy.com/api/unblocker/mcp`                            |
| Transport  | Streamable HTTP                                                         |
| Sign-in    | Header `Authorization: Basic BASE64(username:password)` of a proxy user |

### Tools

| Tool          | What it does                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `unlock_page` | Fetches one page and returns it as Markdown (default), HTML, plain text or a screenshot. Uses 1 result when it succeeds. |
| `get_balance` | How many results are left. Free.                                                                                         |

`unlock_page` takes `url` (required) and optionally `output` (`markdown`, `html`, `text` or `screenshot`), `country` (two-letter code), `js_render` (`true` by default), `wait_selector`, `wait_ms` (up to 30000) and `max_chars` (longest text returned, 1000 to 1000000, 60000 by default; longer pages are cut).

### Set it up

Replace `BASE64` with your proxy user's `username:password` in Base64 (the dashboard does this for you).

{% tabs %}
{% tab title="Cursor" %}
Add to `~/.cursor/mcp.json`, then restart Cursor:

```json
{
  "mcpServers": {
    "dinproxy": {
      "url": "https://app.dinproxy.com/api/unblocker/mcp",
      "headers": { "Authorization": "Basic BASE64" }
    }
  }
}
```

{% endtab %}

{% tab title="Claude Code" %}
Run once in a terminal:

```bash
claude mcp add --transport http dinproxy 'https://app.dinproxy.com/api/unblocker/mcp' \
  --header 'Authorization: Basic BASE64'
```

{% endtab %}

{% tab title="Claude Desktop" %}
Open **Settings → Developer → Edit Config**, add this to `claude_desktop_config.json` and restart Claude. It needs [Node.js](https://nodejs.org) installed (`mcp-remote` connects Claude Desktop to the server):

```json
{
  "mcpServers": {
    "dinproxy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.dinproxy.com/api/unblocker/mcp", "--header", "Authorization:${DINPROXY_AUTH}"],
      "env": { "DINPROXY_AUTH": "Basic BASE64" }
    }
  }
}
```

{% endtab %}

{% tab title="VS Code" %}
Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "dinproxy": {
      "type": "http",
      "url": "https://app.dinproxy.com/api/unblocker/mcp",
      "headers": { "Authorization": "Basic BASE64" }
    }
  }
}
```

{% endtab %}
{% endtabs %}

Other MCP clients work the same way: give them the server URL and the `Authorization` header.

Then ask, for example: *"Use unlock\_page to read <https://example.com/pricing> and list the plans."*

{% hint style="info" %}
A page can take up to 2 minutes. When no results are left, the tool says so; buy more on the Web Unlocker page.
{% endhint %}

## Command-line tool

`dinproxy-unlocker.mjs` fetches a whole list of URLs from a terminal: several at a time, retried safely, each page saved as a file. It needs [Node.js](https://nodejs.org) 18 or later and nothing else.

### Download and sign in

{% tabs %}
{% tab title="macOS / Linux" %}

```bash
curl -O 'https://app.dinproxy.com/app/downloads/dinproxy-unlocker.mjs'
export DINPROXY_USER='1024~myuser'
export DINPROXY_PASSWORD='YOUR_PASSWORD'
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
Invoke-WebRequest 'https://app.dinproxy.com/app/downloads/dinproxy-unlocker.mjs' -OutFile dinproxy-unlocker.mjs
$env:DINPROXY_USER = '1024~myuser'
$env:DINPROXY_PASSWORD = 'YOUR_PASSWORD'
```

{% endtab %}
{% endtabs %}

The **Download CLI** button on the Web Unlocker page gives the same file.

### Use it

```bash
# Every URL in urls.txt (one per line), 5 at a time, into the pages folder
node dinproxy-unlocker.mjs --input urls.txt --out pages --concurrency 5

# One page, printed to the screen
node dinproxy-unlocker.mjs 'https://example.com' --stdout > example.html

# Screenshots from Germany
node dinproxy-unlocker.mjs --input urls.txt --format png --country de
```

| Option                               | Meaning                                                           |
| ------------------------------------ | ----------------------------------------------------------------- |
| `--input FILE`                       | One URL per line (`-` reads standard input; `#` starts a comment) |
| `--out DIR`                          | Where to save results (default `dinproxy-results`)                |
| `--stdout`                           | Print one page's HTML instead of saving it                        |
| `--format`                           | `html` (default), `png` or `html,png`                             |
| `--country CODE`                     | Two-letter country to fetch from                                  |
| `--no-render`                        | Don't run the page's JavaScript                                   |
| `--wait-selector CSS`, `--wait-ms N` | Wait for an element, or a number of milliseconds                  |
| `--concurrency N`                    | Pages at the same time, 1 to 100 (default 5)                      |
| `--retries N`                        | Extra attempts for a failed page, 0 to 10 (default 3)             |
| `--run-id ID`                        | Collect an earlier run's results again (see below)                |
| `--user`, `--password`               | Instead of `DINPROXY_USER` and `DINPROXY_PASSWORD`                |

`node dinproxy-unlocker.mjs --help` lists every option.

### Results

Each page is saved as a file numbered by its place in the list, e.g. `001-example.com-pricing.html` in a list of 100 or more URLs (`.png` for screenshots). `results.jsonl` lists every URL with its file or its error code. The tool ends with exit code 0 when every page succeeded, 1 when some failed, and 2 when an option is wrong or a `--stdout` page failed.

### Retries and paying once

* A page that fails is tried again with a new request; failed attempts are not charged.
* When there is no answer (busy, timeout, lost connection), the tool asks again with the same `Idempotency-Key`, so a page is never paid twice.
* Each run prints a **run ID**. Running the same list, in the same order, again with `--run-id` within 24 hours returns the pages already fetched without charging them again, and fetches the pages the earlier run had not reached. Pages that failed are not tried again under the same run ID: put them in a new run.
* The tool stops when no results are left or the password is wrong.
