Tool reference

The MCP tools monkbrowse exposes. Source of truth: packages/protocol/src/tools.ts.

Targeting: profile and tab

Most tools accept two optional arguments:

• profile — which Chrome profile: a port number (9222), its label, or its profileId. Omit it to use the focused profile (the only connected one, or the most recently used).
• tab — which tab, as the simple number shown in the monkbrowse popup and browser_list_tabs (1, 2, 3…). Omit it to use that profile's active tab.

These are the same numbers the user sees in the extension popup, so a user can say "on tab 2, …" and the AI passes { tab: 2 }. Run browser_list_tabs any time to see the current numbering.

Only shared tabs are reachable. The user toggles which tabs to share in the popup; only those get a number and appear in browser_list_tabs. A tool call against an unshared tab returns an error telling the user to share it. If a tool reports "no tabs are shared," ask the user to toggle a tab on in the popup.

After an action that changes the page, the tool returns a fresh accessibility snapshot so the AI can see the result and pick the next ref.

Navigation

Tool	Arguments	Does
browser_navigate	url, profile?, tab?	Navigate to a URL, wait for load, return a snapshot.
browser_go_back	profile?, tab?	Back in history + snapshot.
browser_go_forward	profile?, tab?	Forward in history + snapshot.
browser_reload	profile?, tab?	Reload the page + snapshot.

Reading

Tool	Arguments	Does
browser_snapshot	profile?, tab?	Accessibility snapshot (URL + title + tree). Includes shadow-DOM and same-origin iframe content. Preferred for structure + getting refs.
browser_get_text	ref?, profile?, tab?	Visible text of the page (or one element) — for reading/summarizing.
browser_screenshot	profile?, tab?	PNG of the tab (brings it to front first, so background tabs work).
browser_get_console_logs	profile?, tab?	Buffered console output (and any auto-handled dialogs).
browser_evaluate	expression, profile?, tab?	Run a JS expression in the page, return its result. Power escape hatch: DOM queries, document.cookie, localStorage, etc.

Interacting

Element-targeting tools take an element (human description) and a ref (from the latest snapshot).

Tool	Arguments	Does
browser_click	element, ref, profile?, tab?	Click an element.
browser_hover	element, ref, profile?, tab?	Hover an element.
browser_type	element, ref, text, submit?, profile?, tab?	Type into an editable element; submit: true presses Enter after.
browser_select_option	element, ref, values[], profile?, tab?	Select option(s) in a <select>.
browser_press_key	key, profile?, tab?	Press a key or combo (Enter, ArrowDown, Ctrl+A, Meta+c).
browser_scroll	direction?, amount?, ref?, profile?, tab?	Scroll the page (to load lazy content) or scroll a ref into view.
browser_drag	startElement, startRef, endElement, endRef, profile?, tab?	Drag one element onto another.
browser_upload_file	ref, path, profile?, tab?	Set a local file on a <input type=file>. The server reads path.

Timing

Tool	Arguments	Does
browser_wait	time?, text?, profile?, tab?	Wait N seconds, or until text appears on the page (polls, up to ~15s).

Tabs & profiles

Tool	Arguments	Does
browser_list_tabs	—	List the shared tabs across every connected profile, numbered.
browser_switch_tab	tab, profile?	Make a shared tab the active tab in its profile.
browser_new_tab	url?, profile?	Open a new tab (auto-shared) and return its number.
browser_close_tab	tab, profile?	Close a shared tab.

Examples

// See everything, everywhere
{ "name": "browser_list_tabs", "arguments": {} }

// Drive a specific profile by port
{ "name": "browser_navigate", "arguments": { "profile": 9223, "url": "https://news.ycombinator.com" } }

// Read a specific tab
{ "name": "browser_snapshot", "arguments": { "profile": 9222, "tab": 2 } }

// Act on the focused profile's active tab (no targeting needed)
{ "name": "browser_type", "arguments": { "element": "Search box", "ref": "e8", "text": "monkbrowse", "submit": true } }

Notes

• Concurrency: calls to different profiles or different tabs run in parallel; two mutating calls to the same tab are serialized so they can't interleave.
• Refs are per-snapshot: a ref (e12) is stamped during a snapshot. If the page changed, capture a new snapshot — a stale ref returns an error rather than clicking the wrong thing.
• Idempotent reads retry; actions don't: a timed-out snapshot/read is retried automatically; a click or type is never silently re-sent.
• Adding a tool? See .claude/rules/mcp-tools.md and the add-mcp-tool skill.