# webshare-proxy-mcp

An [MCP](https://modelcontextprotocol.io) server that routes HTTP requests through [Webshare](https://www.webshare.io/) proxies, with exit-IP verification, rotation, and environment hardening.

## Features

- **Proxy rotation** — pick a random or country-filtered proxy from a Webshare account (direct or backbone mode)
- **Exit-IP verification** — confirm the IP a proxy presents before relying on it
- **Strict proxy routing** — `fetch_via_proxy` never falls back to a direct connection
- **Environment hardening** — generate a permission-restricted (`0600`) env file exporting standard proxy variables

## Requirements

- Python 3.10+
- A [Webshare](https://www.webshare.io/) account with an API key (Dashboard → API → Key)

## Installation

```bash
uv tool install webshare-proxy-mcp
```

Or run ad-hoc from source:

```bash
uv run server.py
```

## Configuration

| Environment variable | Required | Description |
|---|---|---|
| `WEBSHARE_API_KEY` | yes | Webshare API token used for account access |

## Tools

| Tool | Description |
|---|---|
| `list_proxies` | List proxies in the account, with optional country, mode, and validity filters |
| `get_proxy` | Return a ready-to-use proxy as `proxy_url`, `colon_format`, and a ready-to-run `curl` snippet |
| `test_proxy` | Send a request through a proxy and report the exit IP it presents |
| `fetch_via_proxy` | GET a URL strictly through a given proxy; no direct fallback |
| `write_proxyrc` | Write a `0600` env file exporting `PROXY_URL`, `http_proxy`, `https_proxy`, `ALL_PROXY`, and `no_proxy` |

## Client configuration

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "webshare-proxy": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/bayramlcm/webshare-proxy-mcp", "webshare-proxy-mcp"],
      "env": { "WEBSHARE_API_KEY": "YOUR_KEY" }
    }
  }
}
```

### opencode

```json
{
  "mcp": {
    "webshare-proxy": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/bayramlcm/webshare-proxy-mcp", "webshare-proxy-mcp"],
      "environment": { "WEBSHARE_API_KEY": "YOUR_KEY" }
    }
  }
}
```

## Usage

Via MCP tools:

```
get_proxy(country_codes="FR")
→ { "proxy_url": "http://user:pass@host:port", "curl_snippet": "curl -x ... https://api.ipify.org", ... }

test_proxy(host, port, username, password)
→ { "ok": true, "status_code": 200, "exit_ip": "82.23.57.191" }

fetch_via_proxy("https://api.ipify.org", host, port, username, password)
→ { "status_code": 200, "headers": { ... }, "body": "82.23.57.191" }
```

From a shell, using the generated env file:

```bash
source /tmp/proxyrc; curl -s https://api.ipify.org
curl -s -x "$PROXY_URL" https://api.ipify.org
```

> **Note:** exported variables do not survive shell resets between commands. Source the env file on the same command line as the request, or pass the proxy explicitly per request.

## Security

- The API key is read from the environment only; never commit credentials.
- `write_proxyrc` creates files with `0600` permissions because they contain proxy credentials.
- Raw TCP/ICMP tools (`nmap`, `ping`) do not honor HTTP proxy settings; use a proxy chaining tool if needed.
- Only access targets you are authorized to access.

## License

[MIT](LICENSE)