Browser
Control Chrome/Brave/Edge/Chromium browser via Chrome DevTools Protocol (CDP).
CRITICAL: How to Use This Tool
Use navigate to go to a URL. It auto-starts the browser and uses the current tab.
- Do NOT use
open to visit a URL — it creates a NEW tab every time, leaving old tabs open.
- Do NOT call
start before navigate — the browser starts automatically.
- After navigating, use
snapshot to read page content (NOT screenshot).
- Use
screenshot only when you need a visual image, not to read text.
- Use
inspect or snapshot format=accessibility to find CSS selectors before clicking/typing.
Actions Reference
Navigation (use these to move between pages)
| Action |
Description |
navigate |
Primary action. Go to a URL. Auto-starts browser. Uses current tab. Params: url (required) |
back |
Go back in browser history (like browser back button) |
forward |
Go forward in browser history |
reload |
Reload the current page |
scroll |
Scroll the page. Params: direction (up/down/left/right, default: down), amount (pixels, default: viewport height) |
wait |
Wait for conditions. Params: seconds (1-60), text, wait_selector, wait_url, wait_fn |
Reading Page Content
| Action |
Description |
snapshot |
Use this to read page content. Params: format (text/accessibility), max_chars, interactive |
screenshot |
Capture visual image. Returns resized JPEG preview for visual analysis + saves full-res file. Params: full_page, image_type, quality, selector, output_path |
inspect |
List interactive elements with CSS selectors (up to 100 visible elements) |
pdf |
Render current page to PDF. Saves file and returns path. Params: output_path |
Interacting with Elements
| Action |
Description |
click |
Click element. Params: selector (required), double_click, button (left/right/middle) |
type |
Type text. Params: text (required), selector (optional, clicks first), submit (Enter after), slowly |
press |
Press key. Params: key (Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp/Down, Space, F1-F12) |
hover |
Hover over element. Params: selector |
select |
Select dropdown options. Params: selector, values (array) |
fill |
Batch form fill. Params: fields (array of {selector, value, type?}) |
drag |
Drag and drop. Params: selector (source), end_selector (target) |
scroll_into_view |
Scroll element into view. Params: selector |
resize |
Set viewport. Params: width, height |
JavaScript
| Action |
Description |
evaluate |
Execute JavaScript. Params: script (required). Returns result |
Network & Console Monitoring
| Action |
Description |
console |
Browser console messages. Params: level (log/warn/error), clear |
errors |
JavaScript errors. Params: clear |
requests |
Network requests. Params: filter (URL substring), clear |
response_body |
Get response body. Params: filter (URL substring, required), max_chars |
Cookies & Storage
| Action |
Description |
cookies |
Get cookies. Params: url (optional filter) |
set_cookie |
Set cookie. Params: name, value, domain, path, url |
clear_cookies |
Clear all cookies |
get_storage |
Get localStorage/sessionStorage. Params: kind (local/session) |
set_storage |
Set storage entry. Params: kind, name, value |
clear_storage |
Clear storage. Params: kind |
Environment Emulation
| Action |
Description |
set_offline |
Toggle offline mode. Params: enabled |
set_headers |
Set custom HTTP headers. Params: headers (object) |
set_credentials |
Set HTTP basic auth. Params: username, password, clear |
set_geolocation |
Override GPS. Params: latitude, longitude, clear |
set_media |
Color scheme. Params: media (dark/light/no-preference/none) |
set_timezone |
Override timezone. Params: timezone (IANA ID). Omit to reset to UTC |
set_locale |
Override locale. Params: locale (e.g. pt-BR) |
set_device |
Device emulation. Params: device (preset) or width+height, clear |
Device presets: iPhone 14, iPhone 14 Pro Max, iPhone SE, iPad, iPad Pro, Pixel 7, Samsung Galaxy S23, Desktop 1080p, Desktop 1440p.
Tab Management (only for multi-tab scenarios)
| Action |
Description |
tabs |
List all open tabs |
open |
Open a NEW tab (only use when you need multiple tabs). Params: url |
focus |
Switch to a tab. Params: target_id |
close |
Close a tab. Params: target_id (optional, closes current) |
Lifecycle
| Action |
Description |
status |
Check if browser is running |
start |
Launch browser (not needed before navigate) |
stop |
Shut down browser |
Dialog & File
| Action |
Description |
dialog |
Handle JS dialog. Params: accept, prompt_text |
upload |
Set file input. Params: selector, path |
Common Workflows
Visit a page and read its content
navigate url="https://example.com" → auto-starts browser, loads page
snapshot → read the page text content
Fill a form and submit
navigate url="https://example.com/login"
inspect → find form field selectors
type selector="#email" text="user@example.com"
type selector="#password" text="pass123" submit=true
wait text="Welcome" → wait for success
snapshot → verify result
Scroll through a long page
navigate url="https://example.com/article"
snapshot → read visible content
scroll direction=down → scroll one viewport down
snapshot → read more content
scroll direction=down amount=500 → scroll 500px down
Go back/forward
navigate url="https://page1.com"
navigate url="https://page2.com"
back → returns to page1.com
forward → returns to page2.com
reload → reloads page2.com
Save screenshot to a specific path
navigate url="https://example.com"
screenshot output_path="public/home.png" → saves to specified path
screenshot → saves to temp directory (default)
Save PDF to a specific path
navigate url="https://example.com/report"
pdf output_path="public/docs/report.pdf" → saves to specified path
Mobile testing
set_device device="iPhone 14"
navigate url="https://example.com"
screenshot → capture mobile view
Understanding Responses
Every navigation action returns the actual URL, page title, and tab context:
Navigated to: https://example.com | Title: "Example Domain" (tab 1/1)
If a redirect occurred:
Navigated to: https://example.com | Title: "Example" (redirected from http://example.com) (tab 1/1)
If navigation failed:
Error: navigation to https://bad.example failed: net::ERR_NAME_NOT_RESOLVED (tab 1/1)
Screenshot responses include a resized preview image (sent as a visual block you can see) and file info. Without output_path, files go to a temp directory (absolute path). With output_path, use a path relative to the project root:
[image preview is displayed inline for visual analysis]
Screenshot captured (1920x1080, 245KB). Preview: 1024x576 (32KB). Full resolution: public/screenshots/home.png
PDF responses return the file path:
PDF saved: public/docs/report.pdf (156KB)
Wait timeout responses report which conditions failed:
Error: wait timed out after 10s. Conditions not met: text='Welcome' selector='#dashboard'
Error Recovery
- If actions fail with CDP errors: use
stop then navigate to restart.
- "element not found": use
inspect to find correct selectors.
- "page load timed out": use
snapshot to check what loaded.
- If the browser is unresponsive:
stop then try again with navigate.
1---2name: browser3description: Full browser automation via Chrome DevTools Protocol. Navigate pages, interact with UI elements, take screenshots, extract content, manage tabs, emulate devices, handle cookies/storage, monitor network, and control browser state.4---56# Browser78Control Chrome/Brave/Edge/Chromium browser via Chrome DevTools Protocol (CDP).910## CRITICAL: How to Use This Tool1112**Use `navigate` to go to a URL.** It auto-starts the browser and uses the current tab.1314- Do NOT use `open` to visit a URL — it creates a NEW tab every time, leaving old tabs open.15- Do NOT call `start` before `navigate` — the browser starts automatically.16- After navigating, use `snapshot` to read page content (NOT screenshot).17- Use `screenshot` only when you need a visual image, not to read text.18- Use `inspect` or `snapshot format=accessibility` to find CSS selectors before clicking/typing.1920## Actions Reference2122### Navigation (use these to move between pages)2324| Action | Description |25|--------|-------------|26| `navigate` | **Primary action.** Go to a URL. Auto-starts browser. Uses current tab. Params: `url` (required) |27| `back` | Go back in browser history (like browser back button) |28| `forward` | Go forward in browser history |29| `reload` | Reload the current page |30| `scroll` | Scroll the page. Params: `direction` (up/down/left/right, default: down), `amount` (pixels, default: viewport height) |31| `wait` | Wait for conditions. Params: `seconds` (1-60), `text`, `wait_selector`, `wait_url`, `wait_fn` |3233### Reading Page Content3435| Action | Description |36|--------|-------------|37| `snapshot` | **Use this to read page content.** Params: `format` (text/accessibility), `max_chars`, `interactive` |38| `screenshot` | Capture visual image. Returns resized JPEG preview for visual analysis + saves full-res file. Params: `full_page`, `image_type`, `quality`, `selector`, `output_path` |39| `inspect` | List interactive elements with CSS selectors (up to 100 visible elements) |40| `pdf` | Render current page to PDF. Saves file and returns path. Params: `output_path` |4142### Interacting with Elements4344| Action | Description |45|--------|-------------|46| `click` | Click element. Params: `selector` (required), `double_click`, `button` (left/right/middle) |47| `type` | Type text. Params: `text` (required), `selector` (optional, clicks first), `submit` (Enter after), `slowly` |48| `press` | Press key. Params: `key` (Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp/Down, Space, F1-F12) |49| `hover` | Hover over element. Params: `selector` |50| `select` | Select dropdown options. Params: `selector`, `values` (array) |51| `fill` | Batch form fill. Params: `fields` (array of {selector, value, type?}) |52| `drag` | Drag and drop. Params: `selector` (source), `end_selector` (target) |53| `scroll_into_view` | Scroll element into view. Params: `selector` |54| `resize` | Set viewport. Params: `width`, `height` |5556### JavaScript5758| Action | Description |59|--------|-------------|60| `evaluate` | Execute JavaScript. Params: `script` (required). Returns result |6162### Network & Console Monitoring6364| Action | Description |65|--------|-------------|66| `console` | Browser console messages. Params: `level` (log/warn/error), `clear` |67| `errors` | JavaScript errors. Params: `clear` |68| `requests` | Network requests. Params: `filter` (URL substring), `clear` |69| `response_body` | Get response body. Params: `filter` (URL substring, required), `max_chars` |7071### Cookies & Storage7273| Action | Description |74|--------|-------------|75| `cookies` | Get cookies. Params: `url` (optional filter) |76| `set_cookie` | Set cookie. Params: `name`, `value`, `domain`, `path`, `url` |77| `clear_cookies` | Clear all cookies |78| `get_storage` | Get localStorage/sessionStorage. Params: `kind` (local/session) |79| `set_storage` | Set storage entry. Params: `kind`, `name`, `value` |80| `clear_storage` | Clear storage. Params: `kind` |8182### Environment Emulation8384| Action | Description |85|--------|-------------|86| `set_offline` | Toggle offline mode. Params: `enabled` |87| `set_headers` | Set custom HTTP headers. Params: `headers` (object) |88| `set_credentials` | Set HTTP basic auth. Params: `username`, `password`, `clear` |89| `set_geolocation` | Override GPS. Params: `latitude`, `longitude`, `clear` |90| `set_media` | Color scheme. Params: `media` (dark/light/no-preference/none) |91| `set_timezone` | Override timezone. Params: `timezone` (IANA ID). Omit to reset to UTC |92| `set_locale` | Override locale. Params: `locale` (e.g. pt-BR) |93| `set_device` | Device emulation. Params: `device` (preset) or `width`+`height`, `clear` |9495Device presets: iPhone 14, iPhone 14 Pro Max, iPhone SE, iPad, iPad Pro, Pixel 7, Samsung Galaxy S23, Desktop 1080p, Desktop 1440p.9697### Tab Management (only for multi-tab scenarios)9899| Action | Description |100|--------|-------------|101| `tabs` | List all open tabs |102| `open` | Open a NEW tab (only use when you need multiple tabs). Params: `url` |103| `focus` | Switch to a tab. Params: `target_id` |104| `close` | Close a tab. Params: `target_id` (optional, closes current) |105106### Lifecycle107108| Action | Description |109|--------|-------------|110| `status` | Check if browser is running |111| `start` | Launch browser (not needed before navigate) |112| `stop` | Shut down browser |113114### Dialog & File115116| Action | Description |117|--------|-------------|118| `dialog` | Handle JS dialog. Params: `accept`, `prompt_text` |119| `upload` | Set file input. Params: `selector`, `path` |120121## Common Workflows122123### Visit a page and read its content124```125navigate url="https://example.com" → auto-starts browser, loads page126snapshot → read the page text content127```128129### Fill a form and submit130```131navigate url="https://example.com/login"132inspect → find form field selectors133type selector="#email" text="user@example.com"134type selector="#password" text="pass123" submit=true135wait text="Welcome" → wait for success136snapshot → verify result137```138139### Scroll through a long page140```141navigate url="https://example.com/article"142snapshot → read visible content143scroll direction=down → scroll one viewport down144snapshot → read more content145scroll direction=down amount=500 → scroll 500px down146```147148### Go back/forward149```150navigate url="https://page1.com"151navigate url="https://page2.com"152back → returns to page1.com153forward → returns to page2.com154reload → reloads page2.com155```156157### Save screenshot to a specific path158```159navigate url="https://example.com"160screenshot output_path="public/home.png" → saves to specified path161screenshot → saves to temp directory (default)162```163164### Save PDF to a specific path165```166navigate url="https://example.com/report"167pdf output_path="public/docs/report.pdf" → saves to specified path168```169170### Mobile testing171```172set_device device="iPhone 14"173navigate url="https://example.com"174screenshot → capture mobile view175```176177## Understanding Responses178179Every navigation action returns the actual URL, page title, and tab context:180```181Navigated to: https://example.com | Title: "Example Domain" (tab 1/1)182```183184If a redirect occurred:185```186Navigated to: https://example.com | Title: "Example" (redirected from http://example.com) (tab 1/1)187```188189If navigation failed:190```191Error: navigation to https://bad.example failed: net::ERR_NAME_NOT_RESOLVED (tab 1/1)192```193194Screenshot responses include a resized preview image (sent as a visual block you can see) and file info. Without `output_path`, files go to a temp directory (absolute path). With `output_path`, use a path relative to the project root:195```196[image preview is displayed inline for visual analysis]197Screenshot captured (1920x1080, 245KB). Preview: 1024x576 (32KB). Full resolution: public/screenshots/home.png198```199200PDF responses return the file path:201```202PDF saved: public/docs/report.pdf (156KB)203```204205Wait timeout responses report which conditions failed:206```207Error: wait timed out after 10s. Conditions not met: text='Welcome' selector='#dashboard'208```209210## Error Recovery211212- If actions fail with CDP errors: use `stop` then `navigate` to restart.213- "element not found": use `inspect` to find correct selectors.214- "page load timed out": use `snapshot` to check what loaded.215- If the browser is unresponsive: `stop` then try again with `navigate`.
ionclaw-org