aethynio/aethyn-browser-mcp

An MCP 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 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):
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 |