Skip to main content
Glama
deenesjakoruzh
maxmkab

browser-agent

by maxmkab
OverviewSchemaRelated ServersScoreDiscussions
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: Playwright MCP Server

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. 生产环境前的检查

  1. python main.py snapshot --url <目标网站>——所需元素是否进入快照？

  2. 在 headful 模式下以 REQUIRE_APPROVAL=true 本地运行任务。

  3. 同一任务在本地 headless 模式下运行——在部署前捕捉渲染差异。

  4. 之后才部署到 VPS 并启动守护进程。

许可证

MIT

This server cannot be installed

F
license - not found
Not graded
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • superpowers-chrome

    obra
    A
    license
    A
    quality
    A
    maintenance
    Enables direct browser control via Chrome DevTools Protocol, supporting navigation, interaction, content extraction, and screenshots through a single MCP tool.
    1
    341
    MIT

  • codex-browser

    sj18259360196-source
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables Codex to control a visible Chromium browser via MCP tools for navigation, page inspection, and interaction, while keeping sensitive steps like login and captcha under the user's control.
    3
    1
    MIT

  • Web Bridge

    JohnXu22786
    A
    license
    A
    quality
    B
    maintenance
    Browser automation MCP server that uses a real browser to give agents eyes and hands—open pages, click, fill, screenshot, and run scripts via accessibility-tree snapshots.
    22
    MIT

View all related MCP servers

Related MCP Connectors

  • browser-mcp

    Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.

  • Tap

    Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.

  • Aginx Browser

    Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/maxmkab/autonomous-browser-agent'

If you have feedback or need assistance with the MCP directory API, please join our Discord server