Content
# Aethyn Browser MCP — residential-proxy browser control for AI agents (pick the country, one identity per task)
[](./LICENSE)
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.
