# aethynio/aethyn-browser-mcp [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/aethynio/aethyn-browser-mcp  
**GitHub Stars:** 3  
**npm Downloads (last month):** 511  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/aethynio-aethyn-browser-mcp

## Description
Drive a local Playwright browser through residential proxies with the agent choosing the exit country/city and holding one sticky identity per task. 10 tools: launch, navigate, accessibility snapshot, click, type, content extraction, exit-IP verification, and per-task identity rotation. Free trial, no card.

## Tools
Capabilities this server exposes over MCP:

- **aethyn_launch_browser** — Launch a local Chromium routed through a residential proxy exit in a chosen country (and city/state on the Elite tier). Returns a session_id the other aethyn_* tools use. Each session is one sticky identity — a pinned exit IP for the whole task.
- **aethyn_navigate** — Navigate the session's browser to a URL and wait for load. Returns the HTTP status, final URL, and page title — read the page with aethyn_get_content to judge the response yourself. Public data only — respect robots.txt, rate limits, and each site's terms.
- **aethyn_get_content** — Return the current page's content cleaned for reading (markdown by default). Use after navigating to extract data.
- **aethyn_snapshot** — Return a structured accessibility snapshot (roles, names, and [ref=..] handles) of the page. Pass those refs to aethyn_click / aethyn_type. No screenshots needed.
- **aethyn_click** — Click an element. Prefer a 'ref' from aethyn_snapshot (e.g. 'e12'); or pass a 'selector' (CSS, or Playwright role=/text= engine).
- **aethyn_type** — Type text into an input. Prefer a 'ref' from aethyn_snapshot; or a 'selector'. Set submit:true to press Enter after.
- **aethyn_check_exit_ip** — Fetch IP info THROUGH the session's proxy so you can verify the exit country/city actually landed before trusting the page. Returns ip, country, city, org/ASN, and a best-effort is_residential flag.
- **aethyn_new_identity** — Rotate the session to a fresh residential exit (new IP, same country) and clear cookies. Use between independent tasks or after a soft-block.
- **aethyn_close** — Close the session's browser context and free memory. Call this when a task is done.
- **aethyn_list_countries** — List available exit countries (and Elite-tier cities where known). Discover geo options at runtime before launching.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "aethyn-browser-mcp": {
    "command": "npx",
    "args": ["-y","aethyn-browser-mcp"],
    "env": {
      "AETHYN_USERNAME": "",
      "AETHYN_PASSWORD": "",
      "AETHYN_DEFAULT_TIER": "",
      "AETHYN_HEADLESS": "",
      "PROXY_HOST": "",
      "PROXY_PORT": "",
      "PROXY_USERNAME": "",
      "PROXY_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `AETHYN_USERNAME`, `AETHYN_PASSWORD`, `AETHYN_DEFAULT_TIER`, `AETHYN_HEADLESS`, `PROXY_HOST`, `PROXY_PORT`, `PROXY_USERNAME`, `PROXY_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# 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`](https://github.com/aethynio/aethyn-browser-mcp/blob/HEAD/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](https://github.com/aethynio/aethyn-browser-mcp/blob/HEAD/LICENSE) — free to use, copy, and adapt.