# Aethyn Browser MCP — residential-proxy browser control for AI agents (pick the country, one identity per task)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
![MCP](https://img.shields.io/badge/MCP-stdio-informational.svg)
![Playwright](https://img.shields.io/badge/browser-Playwright%20Chromium-2EAD33.svg)

An [MCP](https://modelcontextprotocol.io) server that lets an AI agent drive a **real browser through residential proxies**, choosing the exit **country / city, tier, and a sticky per-task session — at call time.** The browser (Playwright Chromium) runs **locally on your machine**; you bring your own proxy credentials. Defaults to [Aethyn](https://www.aethyn.io/?utm_source=github&utm_medium=referral&utm_campaign=browser-mcp&utm_content=readme-intro) residential proxies, and works with **any HTTP proxy** you configure.

> **The only browser MCP where the agent picks the country and holds one identity per task.**

## Why this exists

- **Playwright MCP** drives a browser well, but its proxy is set **once at server startup** — one static exit for the whole session. The agent can't ask for a Japanese exit for one task and a German exit for the next.
- **Hosted "web scraping" MCPs** hide the proxy and hand back JSON — no runtime control over geo or session identity, and it's their pool at their price.

This server gives the agent **runtime, per-task, steerable geo + sticky identity as tools** — exactly what browser agents need to pull country-specific data (pricing, SERPs, catalogs, availability) and feed it into a chart or pipeline.

## Quickstart

**Add the server to your MCP client** — Claude Desktop (`claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "aethyn-browser": {
      "command": "npx",
      "args": ["-y", "aethyn-browser-mcp"],
      "env": {
        "AETHYN_USERNAME": "aethyn-XXXXX",
        "AETHYN_PASSWORD": "your-proxy-password",
        "AETHYN_DEFAULT_TIER": "premium"
      }
    }
  }
}
```

Chromium is **downloaded automatically** on first install (~170 MB, one-time). If your environment blocks post-install scripts, run it yourself: `npx playwright install chromium`.

> **⚠️ Set the tier to match your plan.** `AETHYN_DEFAULT_TIER` defaults to `premium` (port `2099`). If your account is **Elite**, set it to `elite` (port `5499`) — otherwise traffic hits the Premium port and the proxy returns **407 (auth rejected)**, even though the browser launched fine. The agent can also override per task with `tier: "elite"`.

That's it. Ask your agent something like *"Launch a browser in Japan, open example.co.jp, verify the exit IP is Japanese, and give me the page as markdown."*

## Tools

| Tool | What it does |
|------|--------------|
| `aethyn_launch_browser` | Launch local Chromium through a residential exit in a chosen `country` (+ `city`/`state` on Elite), `tier`, and sticky `session`. Returns a `session_id`. |
| `aethyn_navigate` | Go to a URL; waits for load and returns the HTTP status, final URL, and title. |
| `aethyn_get_content` | Return the page cleaned for reading (`markdown` / `text` / `html`). |
| `aethyn_snapshot` | Accessibility snapshot (roles, names, `[ref=..]` handles) — how the agent decides what to click. |
| `aethyn_click` | Click by `ref` (from the snapshot) or a CSS/role/text `selector`. |
| `aethyn_type` | Type into an input (optionally submit with Enter). |
| `aethyn_check_exit_ip` | Fetch IP info **through the session's proxy** to verify the geo actually landed. |
| `aethyn_new_identity` | Rotate to a fresh exit IP (same country) and clear cookies. |
| `aethyn_close` | Close the session's context and free memory. |
| `aethyn_list_countries` | Discover available countries (and Elite cities) at runtime. |

## How it's different

| | Aethyn Browser MCP | Playwright MCP | Hosted scraping MCPs |
|---|---|---|---|
| Runs the browser | **Local (yours)** | Local | Their cloud |
| Proxy geo chosen by the agent **per task** | **✅ at call time** | ❌ fixed at startup | ❌ not exposed |
| Sticky identity per task (pinned exit IP) | **✅** | ❌ | ❌ |
| Verify the exit geo landed | **✅ `check_exit_ip`** | ❌ | ❌ |
| Bring your own proxy | **✅ any HTTP proxy** | one static proxy | ❌ |

No trash-talk — just the capability delta. (Playwright MCP is great; it just wasn't built for per-task geo.)

## Bring your own proxy

Aethyn is the default, but any HTTP proxy works — point `PROXY_HOST` at it and describe its username format with a template. `[ ... ]` segments are dropped when empty, and `{country} {city} {state} {session} {lifetime}` are filled from the agent's call:

```json
{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "aethyn-browser-mcp"],
      "env": {
        "PROXY_HOST": "gate.your-provider.com",
        "PROXY_PORT": "7000",
        "PROXY_USERNAME": "your-user",
        "PROXY_PASSWORD": "your-pass",
        "PROXY_USERNAME_TEMPLATE": "{username}-country-{country}[-city-{city}]-session-{session}-lifetime-{lifetime}"
      }
    }
  }
}
```

For a plain fixed proxy with no geo in the username, use `"PROXY_USERNAME_TEMPLATE": "{username}"`.

## Configuration

| Env var | Default | Notes |
|---------|---------|-------|
| `AETHYN_USERNAME` / `AETHYN_PASSWORD` | — | Your Aethyn proxy credentials (default provider). |
| `AETHYN_DEFAULT_TIER` | `premium` | `premium` (HTTP `2099`) or `elite` (HTTP `5499`, unlocks city/state). |
| `AETHYN_HEADLESS` | `true` | Set `false` to watch the browser. |
| `AETHYN_MAX_SESSIONS` | `8` | Oldest session is evicted past this cap. |
| `AETHYN_IDLE_TIMEOUT_MIN` | `10` | Idle sessions auto-close after this many minutes. |
| `AETHYN_IPINFO_URL` | `https://ipinfo.io/json` | Endpoint `check_exit_ip` hits (through the proxy). |
| `PROXY_HOST` / `PROXY_PORT` / `PROXY_USERNAME` / `PROXY_PASSWORD` / `PROXY_USERNAME_TEMPLATE` | — | Bring-your-own proxy (overrides the Aethyn default). |

**HTTP proxies only** — Chromium can't authenticate SOCKS5, so this server is HTTP-only by design.

## Guardrails

This tool is for collecting **public data**. Please:
- Respect `robots.txt`, rate limits, and each site's terms and the law. *Can reach ≠ should.*
- No login/credential-wall automation, and **no CAPTCHA solving** — there's no such capability. If a site shows a challenge, read the page and stop rather than trying to bypass it.
- Pace yourself. A residential IP firing dozens of requests per second is still obviously a bot.
- Your credentials stay in your MCP config on your machine; the proxy password is never logged.

## Get credentials

Need residential proxy credentials? The **free trial needs no card**:

**[→ Create an Aethyn account](https://www.aethyn.io/signup?utm_source=github&utm_medium=referral&utm_campaign=browser-mcp&utm_content=readme-cta)** · [Quickstart docs](https://www.aethyn.io/docs/quickstart?utm_source=github&utm_medium=referral&utm_campaign=browser-mcp&utm_content=readme-quickstart) · [Pricing](https://www.aethyn.io/pricing?utm_source=github&utm_medium=referral&utm_campaign=browser-mcp&utm_content=readme-pricing)

## Contributing

PRs welcome — especially **extending [`data/locations.json`](./data/locations.json)** with more countries, cities, and states (single lowercase alphanumeric tokens), and new client examples. Keep it real and runnable; use placeholder credentials only.

## License

[MIT](./LICENSE) — free to use, copy, and adapt.