Aethyn Browser MCP 是一个 MCP 服务器，让 AI 智能体通过住宅代理驱动真实浏览器，并可在调用时选择出口国家/城市、套餐层级（tier）以及每个任务的粘性会话。浏览器（Playwright Chromium）在用户本地机器上运行，代理凭据由用户自行提供。默认使用 Aethyn 住宅代理，同时兼容用户配置的任意 HTTP 代理。
用途与定位 该项目解决的问题是：Playwright MCP 能很好地驱动浏览器，但它的代理在服务器启动时设定一次，整个会话只有一个固定出口，智能体无法为一个任务要求日本出口、下一个任务要求德国出口。托管式“网页抓取”MCP 则隐藏代理并返回 JSON，既不能运行时控制地理出口或会话身份，且使用对方节点池和对方定价。本服务器把运行时的、按任务可操控的地理位置与粘性身份作为工具提供给智能体，正是浏览器智能体获取特定国家数据（价格、SERP、商品目录、可用性）并送入图表或流水线所需的能力。
主要能力
- 在调用时选择代理出口国家/城市与套餐层级。
- 每个任务维持一个粘性会话身份。
- 本地运行 Playwright Chromium 浏览器。
- 默认采用 Aethyn 住宅代理，也可接入任意 HTTP 代理。
- 通过配置用户名模板描述代理用户名格式：方括号 [ ... ] 段落为空时会被丢弃，{country}、{city}、{state}、{session}、{lifetime} 会从智能体的调用中填充。对于用户名不含地理信息的固定代理，可使用 "PROXY_USERNAME_TEMPLATE": "{username}"。
- 仅支持 HTTP 代理：Chromium 无法对 SOCKS5 进行认证，因此该服务器按设计仅支持 HTTP。
使用方式 将服务器添加到 MCP 客户端——Claude Desktop（claude_desktop_config.json）或 Cursor（~/.cursor/mcp.json）。Chromium 会在首次安装时自动下载（约 170 MB，一次性）。若环境阻止安装后脚本，可自行运行：npx playwright install chromium。
需将 tier 与套餐匹配。AETHYN_DEFAULT_TIER 默认为 premium（端口 2099）。若账户为 Elite，需设为 elite（端口 5499）——否则流量会打到 Premium 端口，代理返回 407（认证被拒），即使浏览器已正常启动。智能体也可按任务用 tier: "elite" 覆盖。
配置完成后，可让智能体执行类似指令：“在日本启动浏览器，打开 example.co.jp，验证出口 IP 是日本的，并以 markdown 返回页面。”
代理凭据 默认使用 Aethyn 代理，但任何 HTTP 代理都可使用——将 PROXY_HOST 指向它，并用模板描述其用户名格式。需要住宅代理凭据时，免费试用无需信用卡，可创建 Aethyn 账户并查阅快速上手文档与定价。凭据保留在用户本机的 MCP 配置中；代理密码不会被记录。
适用场景 适用于需要按国家获取公开数据的浏览器智能体任务，例如抓取特定国家/城市的价格、搜索结果页、商品目录、可用性等，并将数据送入图表或数据流水线。
限制与合规 该工具用于收集公开数据，请遵守 robots.txt、速率限制、各站点条款与法律。不要进行登录/凭据墙自动化，也不具备 CAPTCHA 破解能力——若站点出现验证挑战，应读取页面并停止，而非尝试绕过。注意请求节奏，住宅 IP 每秒发出数十个请求依然明显是机器人行为。
许可证与贡献 本项目采用 MIT 许可，可自由使用、复制与改编。欢迎 PR，尤其是向 data/locations.json 添加更多国家、城市和州（单个小写字母数字 token），以及新的客户端示例。请保持真实可运行，仅使用占位凭据。
