内容
# Aethyn 浏览器 MCP — 用于 AI 代理的住宅代理浏览器控制（选择国家，每个任务一个身份）
[](./LICENSE)
一个 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI 代理通过住宅代理驱动一个**真实的浏览器**，选择出口**国家/城市，分层和每个任务的粘性会话** — 在调用时。浏览器（Playwright Chromium）**在您的机器上本地运行**；您需要提供自己的代理凭证。默认使用 [Aethyn](https://www.aethyn.io/?utm_source=github&utm_medium=referral&utm_campaign=browser-mcp&utm_content=readme-intro) 住宅代理，支持**任何您配置的 HTTP 代理**。
> **唯一一个代理可以选择国家并为每个任务保持一个身份的浏览器 MCP。**
## 为什么存在
- **Playwright MCP** 可以很好地驱动浏览器，但其代理在服务器启动时设置**一次** — 一个静态出口用于整个会话。代理无法为一个任务请求日本出口，为下一个任务请求德国出口。
- **托管的“网页抓取”MCP** 隐藏代理并返回 JSON — 没有运行时对地理位置或会话身份的控制，并且是他们的代理池，价格由他们决定。
该服务器为代理提供**运行时、每个任务、 steerable geo + sticky identity 作为工具** — 正是浏览器代理需要的，用于提取国家特定的数据（定价、搜索结果、目录、可用性）并将其馈入图表或管道。
## 快速开始
**将服务器添加到您的 MCP 客户端** — Claude Desktop (`claude_desktop_config.json`) 或 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 将在**首次安装时自动下载**（约 170 MB，一次性）。如果您的环境阻止安装后脚本，请自行运行：`npx playwright install chromium`.
> **⚠️ 设置分层以匹配您的计划。** `AETHYN_DEFAULT_TIER` 默认设置为 `premium`（端口 `2099`）。如果您的帐户是 **Elite**，请将其设置为 `elite`（端口 `5499`）— 否则流量将命中 Premium 端口，代理返回 **407（身份验证拒绝）**，即使浏览器启动正常。代理也可以通过 `tier: "elite"` 在每个任务中覆盖。
就是这样。询问您的代理类似 *"在日本启动浏览器，打开 example.co.jp，验证出口 IP 是否为日本，并将页面以 markdown 格式返回给我。"*
## 工具
| 工具 | 功能 |
|------|--------------|
| `aethyn_launch_browser` | 通过住宅出口在选定的 `country`（`city`/`state` 在 Elite 上）启动本地 Chromium，`tier` 和粘性 `session`。返回 `session_id`。 |
| `aethyn_navigate` | 转到 URL；等待加载并返回 HTTP 状态、最终 URL 和标题。 |
| `aethyn_get_content` | 返回清理后的页面以便阅读（`markdown` / `text` / `html`）。 |
| `aethyn_snapshot` | 可访问性快照（角色、名称、`[ref=..]` 处理）— 代理决定点击的内容。 |
| `aethyn_click` | 通过 `ref`（来自快照）或 CSS/role/text `selector` 点击。 |
| `aethyn_type` | 输入到输入框（可选提交 Enter）。 |
| `aethyn_check_exit_ip` | 通过会话的代理获取 IP 信息以验证实际登陆的地理位置。 |
| `aethyn_new_identity` | 旋转到新的出口 IP（相同国家）并清除 cookie。 |
| `aethyn_close` | 关闭会话的上下文并释放内存。 |
| `aethyn_list_countries` | 在运行时发现可用的国家（和 Elite 城市）。 |
## 它与众不同
| | Aethyn 浏览器 MCP | Playwright MCP | 主机抓取 MCP |
|---|---|---|---|
| 运行浏览器 | **本地（您的）** | 本地 | 他们的云 |
| 代理地理位置由代理人**每个任务**选择 | **✅ 在调用时** | ❌ 启动时固定 | ❌ 不公开 |
| 每个任务的粘性身份（固定的出口 IP） | **✅** | ❌ | ❌ |
| 验证出口地理位置 | **✅ `check_exit_ip`** | ❌ | ❌ |
| 自带代理 | **✅ 任何 HTTP 代理** | 一个静态代理 | ❌ |
没有恶意语言 — 只是能力差异。（Playwright MCP 很棒；它只是不是为每个任务的地理位置而构建的。）
## 自带代理
Aethyn 是默认的，但任何 HTTP 代理都有效 — 将 `PROXY_HOST` 指向它并用模板描述其用户名格式。 `[ ... ]` 在为空时会被删除，并且 `{country} {city} {state} {session} {lifetime}` 将从代理的调用中填充：
```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}"
}
}
}
}
```
对于没有用户名中地理位置的纯固定代理，请使用 `"PROXY_USERNAME_TEMPLATE": "{username}"`.
## 配置
| 环境变量 | 默认值 | 备注 |
|---------|---------|-------|
| `AETHYN_USERNAME` / `AETHYN_PASSWORD` | — | 您的 Aethyn 代理凭证（默认提供商）。 |
| `AETHYN_DEFAULT_TIER` | `premium` | `premium`（HTTP `2099`）或 `elite`（HTTP `5499`，解锁城市/州）。 |
| `AETHYN_HEADLESS` | `true` | 设置 `false` 以查看浏览器。 |
| `AETHYN_MAX_SESSIONS` | `8` | 超过此限制时，最老的会话将被逐出。 |
| `AETHYN_IDLE_TIMEOUT_MIN` | `10` | 空闲会话在多少分钟后自动关闭。 |
| `AETHYN_IPINFO_URL` | `https://ipinfo.io/json` | `check_exit_ip` 访问的端点（通过代理）。 |
| `PROXY_HOST` / `PROXY_PORT` / `PROXY_USERNAME` / `PROXY_PASSWORD` / `PROXY_USERNAME_TEMPLATE` | — | 自带代理（覆盖 Aethyn 默认值）。 |
**仅支持 HTTP 代理** — Chromium 无法验证 SOCKS5，因此该服务器仅限 HTTP 代理。
## 防护措施
该工具用于收集**公共数据**。请：
- 尊重 `robots.txt`、速率限制和每个网站的条款以及法律法规。*可以 ≠ 应该。*
- 不进行登录/凭证墙自动化，**不解决 CAPTCHA** — 没有此类功能。如果网站显示挑战，请阅读页面并停止，而不是尝试绕过它。
- 请自律。住宅 IP 每秒发出数十个请求仍然明显是机器人。
- 您的凭证保留在您的 MCP 配置文件中；代理密码永远不会被记录。
## 获取凭证
需要住宅代理凭证吗？**免费试用不需要信用卡**:
**[→ 创建 Aethyn 帐户](https://www.aethyn.io/signup?utm_source=github&utm_medium=referral&utm_campaign=browser-mcp&utm_content=readme-cta)** · [快速入门文档](https://www.aethyn.io/docs/quickstart?utm_source=github&utm_medium=referral&utm_campaign=browser-mcp&utm_content=readme-quickstart) · [定价](https://www.aethyn.io/pricing?utm_source=github&utm_medium=referral&utm_campaign=browser-mcp&utm_content=readme-pricing)
## 贡献
欢迎 PR — 特别是**扩展 [`data/locations.json`](./data/locations.json)** 添加更多国家、城市和州（单个小写字母数字令牌），以及新的客户端示例。保持真实和可运行；仅使用占位符凭证。
## 许可证
[MIT](./LICENSE) — 免费使用、复制和改编。
