Aethyn Browser MCP is an MCP server that lets AI agents drive a real browser through residential proxies, with the ability to choose the exit country/city, plan tier, and a sticky session per task at call time. The browser (Playwright Chromium) runs on the user's local machine, and proxy credentials are provided by the user. It uses Aethyn residential proxies by default, while also being compatible with any HTTP proxy configured by the user.
Purpose and Positioning The problem this project solves is: Playwright MCP can drive a browser well, but its proxy is set once when the server starts, so the entire session has only one fixed exit, and the agent cannot request a Japan exit for one task and a Germany exit for the next. Hosted "web scraping" MCPs hide the proxy and return JSON, so they neither allow runtime control over the geographic exit or session identity, nor do they use the other party's node pool and the other party's pricing. This server provides the agent with runtime, per-task controllable geolocation and sticky identity as tools, which is exactly the capability a browser agent needs to obtain country-specific data (prices, SERPs, product catalogs, availability) and feed it into charts or pipelines.
Main Capabilities
- Choose the proxy exit country/city and plan tier at call time.
- Maintain a sticky session identity per task.
- Run the Playwright Chromium browser locally.
- Use Aethyn residential proxies by default, and also connect to any HTTP proxy.
- Describe the proxy username format through a configuration username template: empty bracketed [ ... ] segments are dropped, and {country}, {city}, {state}, {session}, {lifetime} are filled in from the agent's call. For fixed proxies whose username does not contain geographic information, you can use "PROXY_USERNAME_TEMPLATE": "{username}".
- HTTP proxies only: Chromium cannot authenticate SOCKS5, so this server supports HTTP only by design.
How to Use Add the server to an MCP client—Claude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json). Chromium is downloaded automatically on first installation (about 170 MB, one-time). If the environment blocks post-install scripts, you canRun it yourself: npx playwright install chromium.
The tier must match the plan. AETHYN_DEFAULT_TIER defaults to premium (port 2099). If the account is Elite, it must be set to elite (port 5499)—otherwise traffic will hit the Premium port and the proxy will return 407 (authentication denied), even if the browser has started normally. The agent can also override per task with tier: "elite".
Once configured, you can have the agent execute instructions like: "Launch a browser in Japan, open example.co.jp, verify the exit IP is Japanese, and return the page in markdown."
Proxy credentials By default the Aethyn proxy is used, but any HTTP proxy can be used—point PROXY_HOST at it and describe its username format with the template. When residential proxy credentials are needed, the free trial requires no credit card; you can create an Aethyn account and consult the quick start documentation and pricing. Credentials remain in the user's local MCP configuration; the proxy password is not logged.
Use cases Suitable for browser agent tasks that need to obtain public data by country, such as scraping prices, search results pages, product catalogs, availability, etc. for a specific country/city, and feeding the data into charts or data pipelines.
Limitations and compliance This tool is for collecting public data; please comply with robots.txt, rate limits, each site's terms, and the law. Do not perform login/credential-wall automation, and it does not have CAPTCHA-solving capability—if a site presents a verification challenge, read the page and stop rather than attempting to bypass it. Pay attention to request pacing; dozens of requests per second from a residential IP are still clearly bot behavior.
License and contributions This project is licensed under MIT and may be freely used, copied, and adapted. PRs are welcome, especially adding more countries, cities, and states to data/locations.json (single lowercase alphanumeric tokens), as well as new client examples. Please keep them genuinely runnable and use only placeholder credentials.
