# HProxy Free Tools
> The free, no-key proxy checker and IP lookup APIs, and the MCP server that offers the free tools to AI assistants. Source: https://hproxy.com/docs

## Proxy checker API

*GET or POST https://hproxy.com/api/proxy-check runs a real live test on any proxy: alive, protocols, anonymity, latency and location. Free, no key.*

URL: https://hproxy.com/docs/free/proxy-checker

#### GET /api/proxy-check (no key)

**Check one proxy.** Check whether a proxy is alive and get its protocols, anonymity grade, latency and location. Free, no key, CORS enabled. Each request runs a **real live test** against the proxy (a dead one can take a few seconds to report).

Two limits apply, and every checker endpoint shares them. **Requests**: 120 in a burst per IP, then 5 a second. **Proxies checked**: 300,000 a day per IP, refilling continuously. A signed-in account, or an [API key](#free-proxy-check-keyed), gets ten times both. Past either you get a `429` with `Retry-After` and a `code` saying which limit it was (`rate_limited`, `daily_budget`, or `busy` when the whole service is at capacity). Every answer reports the daily budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Cost`, so you can pace yourself from the headers.

`status` is the verdict: `alive`, `dead`, `invalid` (we could not read the line), `unresolved` (the hostname has no DNS answer), `forbidden` (a private or reserved address we do not dial) or `unchecked` (no answer inside the time budget; not a verdict, retry the line). For a gateway proxy, `exit_ip` is where your traffic actually comes out, and the location fields describe that address. A dead proxy carries the reason in `failure` (`refused`, `timeout`, `tls_error`, `bad_status`, `no_echo`). Geo and ASN fields fill in when enrichment data exists and are `null` otherwise.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `proxy` | `ip:port (query)` | required | The proxy to test, e.g. 203.0.113.7:1080, or host:port:user:pass for one with a login. |

**Request**

```bash
curl "https://hproxy.com/api/proxy-check?proxy=203.0.113.7:1080"
```

**Response**

```json
{
  "input": "203.0.113.7:1080",
  "status": "alive",
  "alive": true,
  "ip": "203.0.113.7",
  "exit_ip": "203.0.113.7",
  "port": 1080,
  "protocols": ["socks5"],
  "anonymity": "elite",
  "latency_ms": 184,
  "country_code": "US",
  "region": "New York",
  "city": "New York",
  "asn": 14061,
  "asn_org": "DigitalOcean, LLC",
  "is_datacenter": true,
  "failure": null,
  "error": null
}
```

#### POST /api/proxy-check (no key)

**Check up to 1,000 at once.** POST a JSON body with up to **1,000** proxies. They are checked in parallel and the answer comes back in one response within about 25 seconds: a few seconds when they are alive, longer when some never answer. The response is `{ "count": n, "results": [ ... ], "complete": true, "unchecked": 0 }` with the same per-proxy shape, one row for **every** line you sent. A line that did not get an answer inside the time budget comes back with `status: "unchecked"`, and `complete` is then `false`: retry those lines, or stream the list instead. Bigger lists belong on the streaming endpoint below, which takes up to 100,000 and reports each proxy the moment it settles.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `proxies` | `string[]` | required | Up to 1,000 proxy lines per request (ip:port, host:port:user:pass or user:pass@host:port). |

**Request**

```bash
curl -X POST https://hproxy.com/api/proxy-check \
  -H "Content-Type: application/json" \
  -d '{"proxies": ["203.0.113.7:1080", "198.51.100.3:8080"]}'
```

**Response**

```json
{
  "count": 2,
  "results": [
    { "input": "203.0.113.7:1080", "status": "alive", "alive": true, "ip": "203.0.113.7", "port": 1080, "protocols": ["socks5"], "latency_ms": 184, "failure": null, "error": null },
    { "input": "198.51.100.3:8080", "status": "dead", "alive": false, "ip": "198.51.100.3", "port": 8080, "protocols": [], "latency_ms": null, "failure": "timeout", "error": "proxy did not respond" }
  ],
  "complete": true,
  "unchecked": 0
}
```

#### POST /api/free-proxy/check (no key)

**Stream a big list, up to 100,000.** The endpoint behind our [online proxy checker](https://hproxy.com/proxy-checker-online) page. POST the list and read the answer as **NDJSON**: one JSON line per proxy, in the shape above, written the moment that proxy settles, so you can show results while the rest are still running. The same limits apply, counted per proxy.

Two kinds of event lines ride along; skip any line that has an `_event` key you do not know. `{"_event":"progress","done":N,"total":M}` arrives every 15 seconds, and `{"_event":"end","total":M,"done":M,"duration_ms":N}` closes a finished batch. **A stream that stops without the end line was cut** (a network drop, or a restart on our side): the lines you have no row for were not checked, so send just those again.

If your list is big enough that the run takes minutes, hand it over as a [job](#check-jobs-create) instead: nothing stays connected, and an interrupted job resumes by itself.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `proxies` | `string[]` | required | Up to 100,000 proxy lines. |
| `timeout_ms` | `integer` | optional | Per-probe budget, 1,000 to 60,000. Default 8,000. |
| `retries` | `integer` | optional | Extra attempts for a proxy that does not answer, 0 to 3. Default 0. |
| `protocols` | `string[]` | optional | Any of http, https, socks4, socks5. Default all four. |
| `measure_speed` | `boolean` | optional | Also measure download speed through each working proxy (speed_mbps). |
| `measure_udp` | `boolean` | optional | Also test whether each working SOCKS5 proxy relays UDP (supports_udp). |

**Request**

```bash
curl -N -X POST https://hproxy.com/api/free-proxy/check \
  -H "Content-Type: application/json" \
  -d '{"proxies": ["203.0.113.7:1080", "198.51.100.3:8080"], "protocols": ["socks5"]}'
```

**Response (NDJSON)**

```json
{"input":"203.0.113.7:1080","status":"alive","alive":true,"ip":"203.0.113.7","port":1080,"protocols":["socks5"],"latency_ms":184,"failure":null,"error":null}
{"input":"198.51.100.3:8080","status":"dead","alive":false,"ip":"198.51.100.3","port":8080,"protocols":[],"latency_ms":null,"failure":"refused","error":"proxy did not respond"}
{"_event":"end","total":2,"done":2,"duration_ms":2391}
```

#### POST /api/v1/free-proxy/check

**With your API key.** Every checker endpoint also answers under `/api/v1` for an API key: `POST /api/v1/free-proxy/check` streams, `GET` and `POST /api/v1/proxy-check` answer in one response. Same bodies, same result rows, and your account's tier: ten times the requests and 3,000,000 proxies a day, counted on the account rather than on the address, so a whole team behind one office connection is not squeezed into one person's budget. Any key works; checking spends nothing and needs no scope. Errors come back in the usual `/api/v1` shape, `{ "error", "code" }`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key (or Authorization: Bearer hpx_...). |

**Request**

```bash
curl -N -X POST https://hproxy.com/api/v1/free-proxy/check \
  -H "X-API-Key: hpx_..." -H "Content-Type: application/json" \
  -d '{"proxies": ["gate.example.com:7000:user:pass"]}'
```

#### POST /api/v1/proxy-check/jobs

**Hand over a big list as a job.** For the lists that take minutes: hand the list over, get an id back immediately, come back for the results when it is done. Nothing has to stay connected, so a dropped line, a closed laptop or a restart on our side does not cost you the run — a job that is interrupted resumes on the line after the last one answered.

**Accounts only** (an API key, or signed in on the dashboard). The list costs the same as checking it any other way: every line is charged to your daily budget of 3,000,000 when the job is created, and refunded if the job could not be created at all.

The limits that keep this from becoming a flood: up to **100,000** lines per job, **3** queued or running jobs at a time per account, and 20 job creations an hour. Job probes run in the lowest lane, below every live check, so they pause while the service is under load and pick up again by themselves. Results live for **72 hours** after the job ends, then the files are deleted and the job reads `expired`.

Send the list as `{ "proxies": [...] }` with the same options the streaming endpoint takes, or as a `text/plain` body of one proxy per line (what `curl --data-binary @list.txt` sends). Answer is `202` with the job.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key (or Authorization: Bearer hpx_...). |
| `proxies` | `string[]` | required | Up to 100,000 proxy lines. A text/plain body of one line per proxy works too. |
| `label` | `string` | optional | Your own name for the run, up to 64 characters. Shown in the dashboard. |
| `timeout_ms` | `integer` | optional | Per-probe budget, 1,000 to 60,000. Default 8,000. |
| `retries` | `integer` | optional | Extra attempts for a proxy that does not answer, 0 to 3. Default 0. |
| `protocols` | `string[]` | optional | Any of http, https, socks4, socks5. Default all four. |
| `measure_speed` | `boolean` | optional | Also measure download speed through each working proxy (speed_mbps). |
| `measure_udp` | `boolean` | optional | Also test whether each working SOCKS5 proxy relays UDP (supports_udp). |

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/proxy-check/jobs \
  -H "X-API-Key: hpx_..." -H "Content-Type: text/plain" \
  --data-binary @list.txt
```

**Response**

```json
{
  "id": "cj_7f1c0e5a4b3d4f0e9a2c6b8d1e3f5a70",
  "status": "queued",
  "total": 41000,
  "done": 0,
  "alive": 0,
  "label": null,
  "created_at": "2026-09-12T10:04:11Z",
  "started_at": null,
  "finished_at": null,
  "expires_at": null,
  "error": null,
  "results_url": "/api/v1/proxy-check/jobs/cj_7f1c0e5a4b3d4f0e9a2c6b8d1e3f5a70/results",
  "queue_position": 1
}
```

#### GET /api/v1/proxy-check/jobs/{id}

**Watch a job.** The same job body, with `done` and `alive` climbing as lines settle. `status` is `queued` (with `queue_position` while it waits), `running`, `done`, `cancelled`, `failed` (the reason is in `error`) or `expired` (the results have been deleted). Poll it every few seconds, not every few milliseconds — it counts against your request limit like any other call.

`GET /api/v1/proxy-check/jobs` lists your 20 most recent jobs as `{ "count": n, "jobs": [ ... ] }`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key. |
| `id` | `string (path)` | required | The job id you got back from the create call. |

**Request**

```bash
curl https://hproxy.com/api/v1/proxy-check/jobs/cj_7f1c0e5a... \
  -H "X-API-Key: hpx_..."
```

**Response**

```json
{
  "id": "cj_7f1c0e5a4b3d4f0e9a2c6b8d1e3f5a70",
  "status": "running",
  "total": 41000,
  "done": 18734,
  "alive": 2211,
  "started_at": "2026-09-12T10:04:13Z",
  "finished_at": null,
  "expires_at": null,
  "error": null,
  "results_url": "/api/v1/proxy-check/jobs/cj_7f1c0e5a4b3d4f0e9a2c6b8d1e3f5a70/results"
}
```

#### GET /api/v1/proxy-check/jobs/{id}/results

**Download the results.** Everything that has settled, in the format you ask for. It works on a running job too, so you can start reading before the list is finished — and reading does not consume anything: the file stays until the job expires, so you can download it as often as you like.

`format=ndjson` (the default) is one result row per line, the exact shape every checker endpoint returns. `format=txt` is the working proxies only, one line per proxy, ready to paste straight back into whatever you feed proxies to. `format=csv` is a spreadsheet with a header row. Add `only=alive` to drop the dead rows from any format. `txt` and `csv` come back as a download; ndjson streams.

After the retention window the job reads `expired` and this answers `410`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key. |
| `format` | `ndjson | txt | csv` | optional | Default ndjson. txt is the working proxies only; csv carries a header row. |
| `only` | `alive` | optional | Drop the dead rows (txt does this anyway). |

**Request**

```bash
# the working ones, ready to use
curl "https://hproxy.com/api/v1/proxy-check/jobs/cj_7f1c0e5a.../results?format=txt" \
  -H "X-API-Key: hpx_..." -o working.txt
```

**Response (NDJSON)**

```json
{"input":"203.0.113.7:1080","status":"alive","alive":true,"protocols":["socks5"],"exit_ip":"203.0.113.7","anonymity":"elite","latency_ms":184,"country_code":"US","city":"New York","asn":14061,"asn_org":"DigitalOcean, LLC","is_datacenter":true,"failure":null}
{"input":"198.51.100.3:8080","status":"dead","alive":false,"protocols":[],"failure":"timeout"}
```

#### DELETE /api/v1/proxy-check/jobs/{id}

**Cancel a job.** Stops a queued or running job. What it already answered stays downloadable until it expires, so canceling a long run is a fine way to say "that is enough of these". A job that has already finished answers `409`; the lines it did not get to are not refunded.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key. |
| `id` | `string (path)` | required | The job to stop. |

**Request**

```bash
curl -X DELETE https://hproxy.com/api/v1/proxy-check/jobs/cj_7f1c0e5a... \
  -H "X-API-Key: hpx_..."
```

> [!NOTE] **Your proxies stay yours.** The checker tests the proxies you send and returns the results. They are never saved or added to our [free list](https://hproxy.com/free-proxy-list). A job's list and results sit on our disk only until the job expires, then both files are deleted.

> [!NOTE] **Use it from an AI assistant**: AI assistants can call this as the `proxy_check` tool of HProxy's MCP server: add `https://mcp.hproxy.com/mcp` as a remote MCP server, nothing to install and no key. The line for each assistant (Claude, ChatGPT, Cursor, VS Code and more) is on [/tools/ai](https://hproxy.com/tools/ai), and the tools in full are in [the MCP server docs](https://hproxy.com/docs/free/mcp-server).

## IP location and ASN API

*GET https://hproxy.com/api/ip/{ip} returns country, region, city, coordinates, timezone, ASN and ISP for any public IP. Free, no key, CORS enabled, batch supported.*

URL: https://hproxy.com/docs/free/ip-lookup

#### GET /api/ip/{ip} (no key)

**Location and network for any IP.** One GET returns where an IP is and which network runs it: country, region, city, coordinates, timezone, ASN, ASN organization and ISP. No key, no signup, CORS enabled so you can call it straight from a browser or an extension.

This is the same lookup that powers the [free proxy list](https://hproxy.com/free-proxy-list) and our own [proxy checker](https://hproxy.com/proxy-checker), so if you are writing a proxy checker of your own, you can label your results with exactly the data we label ours with. It is read from offline databases, so there is no third-party API in the path.

Two limits apply per IP, and they are deliberately separate. **Requests** on this single-address door are capped at 900 in a burst, refilling 30 per second. **Addresses** are capped by the budget described under the batch endpoint below, and both doors draw on that same budget, so a hundred thousand single lookups cost exactly what one batch of a hundred thousand costs. Every answer reports the address budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Cost`, so you can pace yourself from the headers rather than discovering the limit by being refused. Past either one you get a clean `429` with `Retry-After`.

Responses carry `Cache-Control: public, max-age=21600`: an address's location and ASN move on the order of weeks, so cache them hard rather than re-asking on every run.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ip` | `IPv4 or IPv6` | required | The address to look up, in the path. Private, loopback, link-local, CGNAT and other reserved ranges are rejected with 400 private_ip, because they have no public location. |

**cURL**

```bash
curl "https://hproxy.com/api/ip/45.79.12.44"
```

**Response**

```json
{
  "ip": "45.79.12.44",
  "country": "US",
  "country_name": "United States",
  "region": "Texas",
  "city": "Dallas",
  "latitude": 32.7797,
  "longitude": -96.8022,
  "timezone": "America/Chicago",
  "asn": 63949,
  "asn_org": "Akamai Technologies, Inc.",
  "isp": "Akamai Technologies, Inc.",
  "is_datacenter": false
}
```

**Python**

```python
import requests

r = requests.get("https://hproxy.com/api/ip/45.79.12.44")
geo = r.json()
print(geo["city"], geo["country"], "AS%s" % geo["asn"], geo["asn_org"])
```

#### POST /api/ip (no key)

**Batch: up to 100 000 addresses per call.** If you are labeling a whole proxy list, use this instead of one request per proxy. Send up to **100,000** addresses in one call and get one result per address, **in the same order you sent them**, so you can zip the two lists together without matching on anything.

**You are charged per distinct address, not per request and not per line.** Duplicates are free, because they are free for us: a list that repeats one host across twenty ports is one lookup on our side, so it is one address on your budget, and there is no need to deduplicate before sending. Lines we reject as invalid or private are free for the same reason, since they never reach the lookup at all. Your budget per IP is 120,000 addresses in a burst, refilling 1,000 per second, and 2,000,000 per day.

**Large batches stream.** The response starts arriving as soon as the first addresses resolve rather than after the last one, which is what makes a call this size practical. It is still a single JSON document with a single `results` array in your original order, so `res.json()` and `r.json()` keep working exactly as before; the bytes simply arrive in pieces. Budget a couple of minutes for a fully cold 100 000-address batch. Anything we have looked up in the last six hours comes back from cache, so a list you re-check is far faster than the first run.

Addresses that cannot be resolved come back as `{ "ip": "…", "found": false }` rather than being dropped, so the arrays always line up.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ips` | `string[]` | required | Up to 100 000 IP addresses. A bare JSON array is also accepted. More than 100 000 returns 400 batch_too_large. |

**cURL**

```bash
curl -X POST "https://hproxy.com/api/ip" \
  -H "content-type: application/json" \
  -d '{"ips":["45.79.12.44","24.48.0.1","8.8.8.8"]}'
```

**Response**

```json
{
  "results": [
    { "ip": "45.79.12.44", "country": "US", "city": "Dallas",
      "asn": 63949, "asn_org": "Akamai Technologies, Inc.", "is_datacenter": false },
    { "ip": "24.48.0.1", "country": "CA", "region": "Quebec", "city": "Montreal",
      "asn": 5769, "asn_org": "Videotron Ltee", "is_datacenter": false },
    { "ip": "8.8.8.8", "country": "US", "asn": 15169,
      "asn_org": "Google LLC", "is_datacenter": true }
  ]
}
```

**Node.js**

```js
// Label a whole proxy list in ONE call. Repeats of the same host
// cost nothing, so there is no need to deduplicate first.
const ips = proxies.map((p) => p.split(":")[0]);

const res = await fetch("https://hproxy.com/api/ip", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ ips }), // up to 100 000
});

console.log("addresses charged:", res.headers.get("X-RateLimit-Cost"));
console.log("budget left:", res.headers.get("X-RateLimit-Remaining"));

const { results } = await res.json(); // same order as `ips`

// Bigger than 100 000? Send it in chunks of 100 000.
```

| Status | Meaning |
| --- | --- |
| `200` | Lookup succeeded. A result with "found": false means we have no data for that address, which is not an error. |
| `400 invalid_ip` | Not a valid IPv4 or IPv6 address. Single lookups only: inside a batch that line comes back as { "found": false, "code": "invalid_ip" } and the rest of the batch is unaffected. |
| `400 private_ip` | A private, loopback, link-local, CGNAT or otherwise reserved address. These have no public location. Inside a batch it behaves like invalid_ip above. |
| `400 batch_too_large` | More than 100 000 addresses in one batch. Split the list. |
| `429 rate_limited` | Too many addresses too quickly from your IP. Retry-After tells you how long. |
| `429 daily_quota` | Your IP has spent its daily address budget. It refills continuously, so a smaller batch fits sooner. |
| `429 global_rate_limited` | The free service as a whole is at capacity, not you specifically. Retry-After tells you how long. |
| `503 server_busy` | We are already resolving as many addresses as we can hold. Retry in a few seconds. |

> [!NOTE] **Location and network only.** This API answers where an address is and which network announces it. It deliberately does not return fraud scores, VPN, Tor or proxy detection, or abuse history. If you need those, they are a separate product, not part of the free tier.

> [!WARNING] **`is_datacenter` is best effort.** It reflects how the address's network is classified, and that classification is not perfect: some hosting ranges are recorded as residential and occasionally the reverse. Treat it as a hint, not a verdict. `asn` and `asn_org` are the reliable signal if you need to reason about who runs an address. Country and ASN are accurate; city is absent for anycast addresses rather than guessed.

> [!TIP] Building a proxy checker? Our own desktop checker is open source and uses exactly this endpoint to fill its location and ISP columns. Feel free to do the same.

> [!NOTE] **Use it from an AI assistant**: AI assistants can call this as the `ip_lookup` tool of HProxy's MCP server: add `https://mcp.hproxy.com/mcp` as a remote MCP server, nothing to install and no key. The line for each assistant (Claude, ChatGPT, Cursor, VS Code and more) is on [/tools/ai](https://hproxy.com/tools/ai), and the tools in full are in [the MCP server docs](https://hproxy.com/docs/free/mcp-server).

## MCP server for AI assistants

*HProxy's remote MCP server at https://mcp.hproxy.com/mcp: the free proxy list, the proxy checker and the IP lookup as tools in Claude, ChatGPT, Cursor and any MCP client. No key, nothing to install.*

URL: https://hproxy.com/docs/free/mcp-server

HProxy runs a remote MCP server at `https://mcp.hproxy.com/mcp`. It gives an AI assistant the free proxy list, the proxy checker and the IP lookup as three tools: `proxy_list`, `proxy_check` and `ip_lookup`. No key, no account, nothing to install. It is listed in the official MCP Registry as `com.hproxy/mcp`.

### Add the MCP server to your assistant

#### Claude Code

In a terminal:

```bash
claude mcp add --transport http hproxy https://mcp.hproxy.com/mcp
```

#### Claude and Claude Desktop

Settings, Connectors, Add custom connector, then paste the address:

```text
https://mcp.hproxy.com/mcp
```

#### ChatGPT

Settings, Security and login, turn on Developer mode, then create an app with this address and No authentication (Plus, Pro, Business, Enterprise and Education, on the web):

```text
https://mcp.hproxy.com/mcp
```

#### Cursor

In ~/.cursor/mcp.json:

```json
{ "mcpServers": { "hproxy": { "url": "https://mcp.hproxy.com/mcp" } } }
```

#### VS Code

In .vscode/mcp.json:

```json
{ "servers": { "hproxy": { "type": "http", "url": "https://mcp.hproxy.com/mcp" } } }
```

#### Windsurf

In ~/.codeium/windsurf/mcp_config.json:

```json
{ "mcpServers": { "hproxy": { "serverUrl": "https://mcp.hproxy.com/mcp" } } }
```

#### Gemini CLI

In ~/.gemini/settings.json:

```json
{ "mcpServers": { "hproxy": { "httpUrl": "https://mcp.hproxy.com/mcp" } } }
```

### The three MCP tools

*Tool*

| Field | Type | Description |
| --- | --- | --- |
| `proxy_list` | `country, protocol, anonymity, limit` | Live free proxies from the public pool. All arguments are optional: `country` (two letters), `protocol` (http, https, socks4, socks5), `anonymity` (elite, anonymous, transparent), `limit` (1 to 200, default 25). |
| `proxy_check` | `proxies` | A real live test of up to 25 proxies given as `ip:port`: alive, protocols, anonymity, latency and where each one exits. |
| `ip_lookup` | `ips` | Country, region, city, coordinates, timezone, ASN and network for up to 50 public addresses. |

### MCP server limits and errors

Each tool runs the same limits per IP address as the website's own endpoint for it. The list: 120 requests in a burst, then 2 a second. The checker: 120 requests in a burst, then 5 a second, and 300,000 proxies checked a day. The lookup: 900 requests in a burst, then 30 a second, and 2,000,000 addresses a day. A tool that cannot run answers with `isError` and a sentence; a limit says how many seconds to wait, so a model waits instead of calling again in a loop.

### Claude Code plugin and Gemini CLI extension

#### Claude Code plugin

The server plus a skill that tells Claude how to use it well. In a terminal:

```bash
claude plugin marketplace add hproxy-com/hproxy-mcp
claude plugin install hproxy@hproxy
```

#### Gemini CLI extension

The server plus a short guide for the model. In a terminal:

```bash
gemini extensions install https://github.com/hproxy-com/hproxy-mcp
```

The setup for every assistant is also on GitHub: [hproxy-com/hproxy-mcp](https://github.com/hproxy-com/hproxy-mcp).

### MCP protocol details

Streamable HTTP: one JSON-RPC message per POST and one JSON answer, with no session and no stream. Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. CORS is open for browser-based clients. A browser that opens the address is sent to [/tools/ai](https://hproxy.com/tools/ai).

### The same tools on your own computer

The `hproxy` command carries the same three tools as a local MCP server, started with `hproxy mcp`, plus tools that connect your computer through a proxy. One file for macOS, Linux and Windows, on x64 and ARM, Raspberry Pi included, built in public from the app's source: [the 0.3.8 release](https://github.com/hproxy-com/proxy-all-in-one-tool/releases/tag/cli-v0.3.8). Install it in one line.

#### macOS and Linux

```bash
curl -fsSL https://hproxy.com/install.sh | sh
```

#### Windows, in PowerShell

```powershell
irm https://hproxy.com/install.ps1 | iex
```

Then `claude mcp add hproxy -- hproxy mcp` in Claude Code, or `hproxy list`, `hproxy check` and `hproxy ip` straight from the terminal. The [HProxy app](https://hproxy.com/proxy-checker) carries it too (Windows, macOS and Linux).