de en es ja ko ru zh

browser-agent

Name: browser-agent
Author: maxmkab

by maxmkab

Overview Schema Source Related Servers Discussions Admin

Python

Local

Autonomous Browser Agent — 无截图

代理通过 Playwright 控制真实的 Chromium，而决策由 LLM 基于 页面的结构化文本快照（ref | role | name | 状态）做出，而非图片。不需要视觉模型，任何步骤都不会生成截图。

同一代码库中的三种工作模式：

模式	如何启用	用途
本地，可见浏览器	`HEADLESS=false`	调试、可视化控制
通过 CDP 连接你的真实 Chrome	`CDP_URL=http://127.0.0.1:9222`	真实会话、更好的指纹
VPS 无头 24/7	`HEADLESS=true` + Docker/systemd	按任务队列自主运行

架构

文件	用途
`snapshot.py`	JS 注入：遍历 DOM + 开放 Shadow DOM + iframes，筛选可见的交互元素，`data-agent-ref`，供 LLM 使用的紧凑文本
`browser.py`	Playwright 会话（headless/headful/CDP、stealth-init、代理、屏蔽图片）以及 14 种动作的执行器
`llm.py`	规划器：Anthropic / OpenAI 兼容 / Ollama，严格的动作 JSON 协议
`agent.py`	LangGraph 循环 `observe → decide → act`，历史压缩、循环检测、HITL、限制
`main.py`	CLI：`run`、`login`、`snapshot`、`daemon` + Telegram 通知和确认
`mcp_server.py`	MCP 服务器：为 Claude Code / Cursor / 自定义编排器提供 13 个浏览器工具
`scripts/chrome-cdp.*`	以调试端口启动你的 Chrome（Linux/macOS 和 Windows）
`Dockerfile`	基于 `mcr.microsoft.com/playwright/python` 的镜像，用于 VPS

Related MCP server: project-tendril

1. 在本地电脑上安装

git clone https://github.com/maxmkab/autonomous-browser-agent.git
cd autonomous-browser-agent

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
playwright install chromium

cp .env.example .env             # вписать ANTHROPIC_API_KEY

不消耗 LLM 的检查方式——查看模型到底看到了什么：

python main.py snapshot --url https://example.com

以可见浏览器运行任务：

HEADLESS=false python main.py run \
  --task "Найди раздел с ценами и извлеки все тарифы через extract" \
  --url https://example.com \
  --json state/report.json

2. 嵌入你的真实浏览器（CDP）

代理可以在自己的纯净 Chromium 之外工作，而是在你的 Chrome 中——带有真实会话、扩展程序和真实的指纹。无需安装任何扩展——通过 Chrome DevTools Protocol 进行控制。

# 1) запустить Chrome с открытым портом (отдельный профиль для агента)
chmod +x scripts/chrome-cdp.sh
./scripts/chrome-cdp.sh 9222          # Windows: scripts\\chrome-cdp.bat 9222

# 2) в другом терминале отдать задачу агенту в этом же браузере
CDP_URL=http://127.0.0.1:9222 python main.py run --task "..."

在此模式下，代理不会触碰 storage_state.json：会话取自 Chrome 配置文件。首次启动——手动登录所需服务，之后配置文件会记住它们。

3. 通过 MCP 嵌入 Claude Code / Cursor

mcp_server.py 启动一个使用 stdio 传输的 MCP 服务器。工具： browser_open、browser_snapshot、browser_click、browser_type、browser_select、 browser_check、browser_scroll、browser_press、browser_back、browser_tabs、 browser_save_session、browser_run_task、browser_close。

Claude Code 的配置（~/.claude.json 或项目根目录下的 .mcp.json）：

{
  "mcpServers": {
    "browser-agent": {
      "command": "/absolute/path/autonomous-browser-agent/.venv/bin/python",
      "args": ["/absolute/path/autonomous-browser-agent/mcp_server.py"],
      "env": {
        "HEADLESS": "false",
        "CDP_URL": "http://127.0.0.1:9222",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "REQUIRE_APPROVAL": "true"
      }
    }
  }
}

或者一条命令：

claude mcp add browser-agent -- /absolute/path/.venv/bin/python /absolute/path/mcp_server.py

之后，Claude Code 中的模型通过 browser_snapshot → browser_click → browser_snapshot 循环驱动浏览器，只获取文本快照。浏览器会话在调用之间保持存活，因此可以逐步引导场景。要实现完全自主，可使用 browser_run_task——代理自行运行循环并返回 JSON 报告。

4. 将授权迁移到服务器

# локально, в видимом окне: залогинился → Enter в консоли
HEADLESS=false python main.py login --url https://site.ru/login

# переносим cookies + localStorage на сервер
scp state/storage_state.json root@YOUR_VPS_IP:/opt/browser-agent/state/

5. 部署到 VPS（Ubuntu 24.04 + Docker）

mkdir -p /opt/browser-agent/state && cd /opt/browser-agent
git clone https://github.com/maxmkab/autonomous-browser-agent.git .
cp .env.example .env && nano .env

docker build -t browser-agent .
docker run -d --name browser-agent --restart unless-stopped \
  --shm-size=1g \
  --env-file .env \
  -v /opt/browser-agent/state:/app/state \
  browser-agent

--shm-size=1g 是必需的：在默认 64 MB /dev/shm 的容器中，Chromium 在重页面上会崩溃。

在服务器上运行一次性任务：

docker exec -it browser-agent python main.py run --task "..." --url https://...

不使用 Docker（systemd）

apt update && apt install -y python3-venv
cd /opt/browser-agent && python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
playwright install --with-deps chromium

/etc/systemd/system/browser-agent.service：

[Unit]
Description=Autonomous browser agent
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/browser-agent
EnvironmentFile=/opt/browser-agent/.env
ExecStart=/opt/browser-agent/.venv/bin/python main.py daemon --interval 300
Restart=always
RestartSec=10
StandardOutput=append:/var/log/browser-agent.log
StandardError=append:/var/log/browser-agent.log

[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now browser-agent
journalctl -u browser-agent -f

6. 任务下发与 n8n

守护进程读取 state/tasks.jsonl——一行 = 一个任务：

{"id":"price-check-1","task":"Открой карточку товара, извлеки цену и наличие через extract","url":"https://site.ru/item/123"}
{"id":"lead-form","task":"Заполни форму заявки: имя Иван, телефон +79990000000. Отправку подтвердит человек."}

结果写入 state/results.jsonl，包含 success、result、extracted、 steps、tokens_in/out 字段以及完整的 history 轨迹。n8n 可以将任务写入该文件（Execute Command / SSH 节点）并读取结果。

7. 节省 Token

无截图：只有文本，无需视觉模型。
DOM 过滤：只有可见的、名称非空的交互元素进入上下文，每帧最多 250 个。
在网络层面屏蔽图片/字体/媒体（BLOCK_MEDIA=true）。
历史压缩（HISTORY_WINDOW）：仅对最近几步保留完整快照，旧步骤折叠为 action → result。
循环检测：如果快照指纹不变，模型会收到更换策略的指示。

8. 安全

符合 RISKY_PATTERNS（支付、购买、下单、删除、发送、 checkout、pay、delete）的动作需要确认：本地在控制台确认，服务器上通过 Telegram 回复“是” （APPROVAL_MODE=telegram）。ALLOW_EVAL=false 默认禁止执行任意 JS。所有动作错误都会作为 observation 返回给模型，不会导致进程崩溃。密钥仅存储在 .env 中，该文件已从 git 排除。

9. 生产环境前的检查

python main.py snapshot --url <目标网站>——所需元素是否进入快照？
在 headful 模式下以 REQUIRE_APPROVAL=true 本地运行任务。
同一任务在本地 headless 模式下运行——在部署前捕捉渲染差异。
之后才部署到 VPS 并启动守护进程。

许可证

MIT

This server cannot be deployed

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Related MCP Connectors

agent-browser A
com.scriptmasterlabs
A real Chromium browser agents pay for per action in USDC via x402 — hosted MCP, free local stdio.
Browser Automation Agent Orchestration Payments & Billing
61
https://agent-browser-r7d2.onrender.com/mcp
browser-mcp
io.github.Shreyas-Profile
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Browser Automation Web Scraping
2
https://browser.regiq.in/api/mcp
BrowserHereOAuth
app.1ts.browserhere
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Browser Automation Agent Orchestration
1
https://browserhere.1ts.app/mcp
Irmu — Web Data MCPOAuth
io.github.polgoide
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Browser Automation Web Scraping Agent Orchestration
1
https://app.irmu.com/mcp

Related MCP Servers

Playwright MCP Server
Browser Automation Testing & QA Tools
muhammadraheel-vd
F
license
Not graded
quality
D
maintenance
Enables browser automation through the MCP protocol, allowing AI agents to control a real browser using accessibility snapshots and natural language commands.
Updated 4 months ago (2026-06-22 05:51 UTC)
-
project-tendril
Browser Automation Web Scraping Search
gadgethd
A
license
Not graded
quality
A
maintenance
Enables AI agents to operate an isolated local Chromium browser through MCP, with semantic snapshots, ref-based actions, search, research, crawling, and CDP access.
Updated 5 hours ago (2026-11-02 05:22 UTC)
Apache 2.0
Playwright MCP Server
Browser Automation Agent Orchestration Web Scraping
tomscoppock
A
license
Not graded
quality
B
maintenance
Enables AI agents and clients to control a real Chromium browser through MCP tool calls, including navigation, clicking, typing, JavaScript evaluation, screenshots, and DOM snapshots. Supports multiple isolated sessions over authenticated HTTP with no disk writes.
Updated 2 months ago (2026-09-08 15:58 UTC)
Apache 2.0
jev-ultrafast-mcp
Browser Automation Agent Orchestration
jiawei686
A
license
A
quality
A
maintenance
Enables AI agents to drive a Chromium browser over MCP, reading pages as a numbered list of controls and performing actions like clicking, filling forms, and asserting page state without screenshots or API keys.
Updated a month ago (2026-09-23 12:26 UTC)
10
50 PyPI
20
MIT