{
  "markdown": "# Aethyn Browser MCP — residential-proxy browser control for AI agents (pick the country, one identity per task)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n![MCP](https://img.shields.io/badge/MCP-stdio-informational.svg)\n![Playwright](https://img.shields.io/badge/browser-Playwright%20Chromium-2EAD33.svg)\n\nAn [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.\n\n> **The only browser MCP where the agent picks the country and holds one identity per task.**\n\n## Why this exists\n\n- **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.\n- **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.\n\nThis 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.\n\n## Quickstart\n\n**Add the server to your MCP client** — Claude Desktop (`claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"aethyn-browser\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"aethyn-browser-mcp\"],\n      \"env\": {\n        \"AETHYN_USERNAME\": \"aethyn-XXXXX\",\n        \"AETHYN_PASSWORD\": \"your-proxy-password\",\n        \"AETHYN_DEFAULT_TIER\": \"premium\"\n      }\n    }\n  }\n}\n```\n\nChromium is **downloaded automatically** on first install (~170 MB, one-time). If your environment blocks post-install scripts, run it yourself: `npx playwright install chromium`.\n\n> **⚠️ 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\"`.\n\nThat'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.\"*\n\n## Tools\n\n| Tool | What it does |\n|------|--------------|\n| `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`. |\n| `aethyn_navigate` | Go to a URL; waits for load and returns the HTTP status, final URL, and title. |\n| `aethyn_get_content` | Return the page cleaned for reading (`markdown` / `text` / `html`). |\n| `aethyn_snapshot` | Accessibility snapshot (roles, names, `[ref=..]` handles) — how the agent decides what to click. |\n| `aethyn_click` | Click by `ref` (from the snapshot) or a CSS/role/text `selector`. |\n| `aethyn_type` | Type into an input (optionally submit with Enter). |\n| `aethyn_check_exit_ip` | Fetch IP info **through the session's proxy** to verify the geo actually landed. |\n| `aethyn_new_identity` | Rotate to a fresh exit IP (same country) and clear cookies. |\n| `aethyn_close` | Close the session's context and free memory. |\n| `aethyn_list_countries` | Discover available countries (and Elite cities) at runtime. |\n\n## How it's different\n\n| | Aethyn Browser MCP | Playwright MCP | Hosted scraping MCPs |\n|---|---|---|---|\n| Runs the browser | **Local (yours)** | Local | Their cloud |\n| Proxy geo chosen by the agent **per task** | **✅ at call time** | ❌ fixed at startup | ❌ not exposed |\n| Sticky identity per task (pinned exit IP) | **✅** | ❌ | ❌ |\n| Verify the exit geo landed | **✅ `check_exit_ip`** | ❌ | ❌ |\n| Bring your own proxy | **✅ any HTTP proxy** | one static proxy | ❌ |\n\nNo trash-talk — just the capability delta. (Playwright MCP is great; it just wasn't built for per-task geo.)\n\n## Bring your own proxy\n\nAethyn 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"browser\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"aethyn-browser-mcp\"],\n      \"env\": {\n        \"PROXY_HOST\": \"gate.your-provider.com\",\n        \"PROXY_PORT\": \"7000\",\n        \"PROXY_USERNAME\": \"your-user\",\n        \"PROXY_PASSWORD\": \"your-pass\",\n        \"PROXY_USERNAME_TEMPLATE\": \"{username}-country-{country}[-city-{city}]-session-{session}-lifetime-{lifetime}\"\n      }\n    }\n  }\n}\n```\n\nFor a plain fixed proxy with no geo in the username, use `\"PROXY_USERNAME_TEMPLATE\": \"{username}\"`.\n\n## Configuration\n\n| Env var | Default | Notes |\n|---------|---------|-------|\n| `AETHYN_USERNAME` / `AETHYN_PASSWORD` | — | Your Aethyn proxy credentials (default provider). |\n| `AETHYN_DEFAULT_TIER` | `premium` | `premium` (HTTP `2099`) or `elite` (HTTP `5499`, unlocks city/state). |\n| `AETHYN_HEADLESS` | `true` | Set `false` to watch the browser. |\n| `AETHYN_MAX_SESSIONS` | `8` | Oldest session is evicted past this cap. |\n| `AETHYN_IDLE_TIMEOUT_MIN` | `10` | Idle sessions auto-close after this many minutes. |\n| `AETHYN_IPINFO_URL` | `https://ipinfo.io/json` | Endpoint `check_exit_ip` hits (through the proxy). |\n| `PROXY_HOST` / `PROXY_PORT` / `PROXY_USERNAME` / `PROXY_PASSWORD` / `PROXY_USERNAME_TEMPLATE` | — | Bring-your-own proxy (overrides the Aethyn default). |\n\n**HTTP proxies only** — Chromium can't authenticate SOCKS5, so this server is HTTP-only by design.\n\n## Guardrails\n\nThis tool is for collecting **public data**. Please:\n- Respect `robots.txt`, rate limits, and each site's terms and the law. *Can reach ≠ should.*\n- 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.\n- Pace yourself. A residential IP firing dozens of requests per second is still obviously a bot.\n- Your credentials stay in your MCP config on your machine; the proxy password is never logged.\n\n## Get credentials\n\nNeed residential proxy credentials? The **free trial needs no card**:\n\n**[→ 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)\n\n## Contributing\n\nPRs 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.\n\n## License\n\n[MIT](./LICENSE) — free to use, copy, and adapt.\n",
  "bytes": 7452,
  "sha": "141cf05baf8e8cf5a330afc54288212b2c0a648dbb67ceaea33184f4ea0f612c",
  "repo_slug": "aethynio/aethyn-browser-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aethynio_aethyn_browser_mcp_bfd7c75d/readme"
}