browser-mcp — beri AI agent Anda browser sungguhan 🌐🤖

MCP server standalone yang memberi AI agent (opencode, Claude Code/Desktop, Cursor, Cline, dsb) kemampuan browser penuh via Chromium lokal + CDP:

• 👁️ Lihat halaman — snapshot DOM compact (mata utama AI), screenshot, visual grounding (x,y), combined view

• 🖱️ Aksi manusiawi — klik/type/keys/scroll + hover/move/dblclick/rightclick/drag (easing+jitter, lolos slider GeeTest)

• 🕷️ Recon otonom — spider BFS in-scope, ekstraktor API/GraphQL ala LinkFinder, HAR-lite, console hook, probe introspeksi GraphQL

• 🔐 Auth 2-akun — vault attacker/victim untuk differential testing (IDOR/priv-esc), password ter-redact di audit

• 🛠️ Burp-like first-class — intercept (request+response), repeater, intruder sniper, match-replace, scope allowlist, collaborator OOB

• 🛡️ Aman by default — scope check di semua navigasi/HTTP keluar, audit audit.jsonl dengan redact kredensial

• 📦 Zero-deployment hell — 1 repo, stdlib + websocket-client saja, backend CDP di-vendor (vendor_browser_local.py), tanpa binary global

47 tools. 1 perintah install. Browser tetap di mesin Anda — tidak ada cloud, tidak ada data keluar.

Demo 30 detik

git clone https://github.com/eye-fox/browser-mcp.git
cd browser-mcp
./install.sh
# restart opencode / AI client Anda, lalu suruh agent:
# "launch browser-mcp session demo, scope ke example.com, navigate, snapshot"
python3 examples/quickstart.py   # tanpa LLM: bukti end-to-end lewat stdio

Related MCP server: project-tendril

Cara kerja

flowchart LR
    Agent["AI agent"] -- "MCP stdio<br/>JSON-RPC" --> Server["server.py"]
    Server -- "subprocess" --> Vendor["vendor_browser_local.py"]
    Vendor -- "CDP ws://" --> Chrome["Chromium lokal"]
    Server --- Scope["scope.json<br/>allowlist/blocklist"]
    Server --- Audit["audit.jsonl<br/>redacted"]
    Server --- Vault["auth_vault.json<br/>2 akun, 600"]
    Server --- Sessions["sessions.json<br/>sessionId → cdp_url"]

Syarat

Install

./install.sh

Script melakukan: cek python → install websocket-client → deteksi chromium (auto-patch BROWSER di vendor) → chmod +x → init scope.json / auth_vault.json (600) / sessions.json / audit.jsonl dari .example → auto-register ke ~/.config/opencode/opencode.json → smoke test tools/list (harus ≥40 tools).

Opsi:

./uninstall.sh   # hapus entri MCP + matikan daemon, repo tidak dihapus

Config manual (non-opencode)

Claude Desktop / Cursor / Cline (mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/browser-mcp/server.py"]
    }
  }
}

Template siap copy: mcp.json.example. Untuk opencode mentah: opencode.json.snippet.

Struktur repo

browser-mcp/
├── install.sh              # setup full: deps + chromium detect + opencode register + smoke test
├── uninstall.sh            # cabut entri MCP + kill daemon
├── server.py               # MCP stdio server (47 tools, scope+audit+redact)
├── vendor_browser_local.py # backend CDP Chromium (stealth, intercept, cookies, dsb) — di-vendor
├── requirements.txt        # websocket-client saja
├── SKILL.md                # instruksi agent (copy ke skill-dir bila perlu)
├── scope.json.example      # -> scope.json (allowlist; default disabled)
├── auth_vault.json.example # -> auth_vault.json (chmod 600)
├── opencode.json.snippet   # referensi config opencode
├── mcp.json.example        # referensi config generik MCP
├── examples/quickstart.py  # e2e tanpa LLM: launch→scope→navigate→snapshot→close
├── scripts/smoke_test.py   # initialize + tools/list, exit 0 bila ≥40 tools
├── LICENSE (MIT)
└── .gitignore (melindungi audit/sessions/vault asli)

scope.json, auth_vault.json, sessions.json, audit.jsonl adalah runtime — tidak ikut ke git (lihat .gitignore). Yang dipublish hanya .example.

Pakai di agent (pola baku)

1. mcp_browser_launch {"sessionId":"s1"} → simpan sessionId

2. mcp_scope_set {"allowed":["target.com"],"enabled":true}

3. mcp_browser_spider {"sessionId":"s1","startUrl":"https://target.com","maxPages":20,"depth":2}

4. Per halaman menarik: mcp_browser_js_endpoints + mcp_browser_console + mcp_browser_network_har

5. mcp_browser_snapshot → mcp_browser_click/type (wait:"idle") → snapshot lagi → mcp_browser_eval verifikasi value

6. Auth differential: mcp_auth_vault set victim/attacker, switch bergantian

7. Intercept hanya saat tahu momennya: mcp_intercept_set(pattern) → aksi pemicu → mcp_intercept_poll langsung → mcp_intercept_continue (forward|drop|modify|fulfill, id:"all" untuk lepas semua)

8. mcp_repeater_send (replay tanpa browser) → mcp_intruder_fuzz (wordlist inline, auto URL-encode) → mcp_browser_graphql probe → mcp_collaborator_start/poll untuk OOB

9. mcp_history_list + HAR review → mcp_browser_close

Aturan detail + 47 tools: lihat SKILL.md.

Tips anti-nyangkut (dari pengalaman)

• Tombol tak ada di elements → mcp_browser_submit(formId) atau keys Enter.

• CAPTCHA gambar/checkbox → mcp_browser_ground, klik via x,y dari gambar.

• Slider GeeTest / canvas → mcp_browser_view lalu mcp_browser_drag(x1,y1,x2,y2).

• Session Connection refused / hang setelah intercept → mcp_browser_recover atau attach sessionId baru, jangan retry session yang wedge.

• poll harus langsung setelah trigger — eval-fetch yang menunggu = wedge.

Keamanan

• Scope allowlist ditegakkan di navigate, repeater_send, intruder_fuzz, graphql. Default scope.json.example = disabled agar demo jalan; aktifkan sebelum hunting target nyata.

• audit.jsonl: key sensitif (password/token/secret/cookie/api-key/bearer) di-redact + body dipotong 500 char. Jangan commit file runtime.

• Vault 600. Jangan taruh kredensial asli di .example.

• Hanya pakai terhadap target yang Anda punya izin uji.

Publish ke GitHub (checklist)

cd browser-mcp
# pastikan tidak ada secret bocor:
grep -ri "password\|token\|api.key\|bearer" --include="*.py" --include="*.md" --include="*.json" --include="*.sh" . | grep -v example | grep -v REDACT || echo "bersih"
git init && git add . && git commit -m "browser-mcp standalone v0.4.0" && git branch -M main
gh repo create browser-mcp --public --source=. --push

Troubleshooting

Lisensi

MIT — lihat LICENSE.