Browser API

Tools, not just functions

The functions below are registered as MCP tools by make_browser_server(), named browser_<member>; which ones are registered depends on the profile and the opt-in list. Their exact model-visible descriptions are in the Tool Reference, and how to use them is on the Browser server page.

Browser Server

doc_processing_std_tools.browser

Browser server: drive a real Chromium through element references.

Modelled on Anthropic's browser_toolset_20260801: each member becomes one MCP tool named browser_<member> (browser_navigate, browser_left_click, browser_read_page, ...). Arguments are flat: a target is ref (from browser_read_page / browser_find) or x + y in screenshot pixels. Every tool also takes an optional tab_id (except the tab tools) and an optional intent, which is logged and otherwise ignored.

Results are text ending in a "Tab Context" footer that lists the open tabs, plus lines for tabs that opened and downloads that started or finished since the last call. browser_screenshot and browser_zoom return an image.

Which tools exist:

• DPTTOOLS_BROWSER_TOOLS=core (default): 18 tools.
• DPTTOOLS_BROWSER_TOOLS=full: Anthropic's 27 default members.

Playwright is imported only when a tool runs, so this module imports without the [browser] extra. The composed launcher includes this server only when DPTTOOLS_ENABLE_BROWSER=true.

browser_close_tab(tab_id, intent=None, ctx=None) async

Close a tab.

Parameters:

Name	Type	Description	Default
tab_id	int	The tab to close.	required
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_double_click(ref=None, x=None, y=None, modifiers=None, tab_id=None, intent=None, ctx=None) async

Double-click an element or a point (for example to select a word).

Target an element with ref (preferred), or with x and y in screenshot pixels.

Parameters:

Name	Type	Description	Default
ref	str | None	Element ref such as "ref_12".	None
x	int | None	Horizontal position in screenshot pixels (with y).	None
y	int | None	Vertical position in screenshot pixels (with x).	None
modifiers	str | None	Keys to hold.	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_file_upload(ref, paths, tab_id=None, intent=None, ctx=None) async

Attach files to a file input (opt-in).

Files must be in the upload directory the operator configured; give paths relative to it (or absolute paths inside it).

Parameters:

Name	Type	Description	Default
ref	str	Element ref of the file input.	required
paths	list[str]	Files to attach.	required
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_find(query, tab_id=None, intent=None, ctx=None) async

Find elements on the page matching a short description, with their refs.

Matching is by words (the element's role, label, placeholder and nearby text), not by meaning: "search box", "Sign in button", "email". Returns up to 20 matches. If nothing matches, use browser_read_page(filter="interactive").

Parameters:

Name	Type	Description	Default
query	str	Words describing the element.	required
tab_id	int | None	Tab to search (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_form_input(ref, value, tab_id=None, intent=None, ctx=None) async

Set a form field's value directly: text field, select, checkbox or radio.

Selects take an option's value or visible label; checkboxes and radios take true or false.

Parameters:

Name	Type	Description	Default
ref	str	Element ref of the field.	required
value	str | int | float | bool	The value to set.	required
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_get_page_text(tab_id=None, intent=None, ctx=None) async

Get the readable text of the page, main content first.

The cheapest way to read an article, a statement or search results. Has no refs; use browser_read_page or browser_find to act on elements.

Parameters:

Name	Type	Description	Default
tab_id	int | None	Tab to read (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_hold_key(text, duration, tab_id=None, intent=None, ctx=None) async

Hold a key or chord down for a number of seconds (at most 30).

Parameters:

Name	Type	Description	Default
text	str	The key or chord, such as "shift" or "ArrowRight".	required
duration	float	Seconds to hold, at most 30.	required
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_hover(ref=None, x=None, y=None, modifiers=None, tab_id=None, intent=None, ctx=None) async

Move the mouse over an element or a point, for menus and tooltips.

Target an element with ref (preferred), or with x and y in screenshot pixels.

Parameters:

Name	Type	Description	Default
ref	str | None	Element ref such as "ref_12".	None
x	int | None	Horizontal position in screenshot pixels (with y).	None
y	int | None	Vertical position in screenshot pixels (with x).	None
modifiers	str | None	Keys to hold while hovering.	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_javascript_exec(expression, tab_id=None, intent=None, ctx=None) async

Run a JavaScript expression in the page and return its value (opt-in).

The value is returned as text (JSON for objects); a promise is awaited. Use only when the other tools cannot do the job.

Parameters:

Name	Type	Description	Default
expression	str	The JavaScript expression, or a function body like "() => document.title".	required
tab_id	int | None	Tab to run in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_key(text, repeat=1, tab_id=None, intent=None, ctx=None) async

Press a key, a chord, or a space-separated sequence of them.

Examples: "Enter", "ctrl+a", "shift+Tab", "Escape", "ctrl+a Delete". Key names follow xdotool (Return, BackSpace, Page_Down) or the usual names (Enter, Backspace, PageDown, ArrowLeft).

Parameters:

Name	Type	Description	Default
text	str	The key, chord or sequence.	required
repeat	int	Times to press the whole sequence, 1-100 (default 1).	1
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_left_click(ref=None, x=None, y=None, modifiers=None, tab_id=None, intent=None, ctx=None) async

Click an element or a point with the left mouse button.

Target an element with ref (from browser_read_page or browser_find; preferred), or with x and y in screenshot pixels. The result names the element that was clicked.

Parameters:

Name	Type	Description	Default
ref	str | None	Element ref such as "ref_12".	None
x	int | None	Horizontal position in screenshot pixels (with y).	None
y	int | None	Vertical position in screenshot pixels (with x).	None
modifiers	str | None	Keys to hold, such as "ctrl" or "shift+ctrl".	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_left_click_drag(from_x, from_y, ref=None, x=None, y=None, tab_id=None, intent=None, ctx=None) async

Drag with the left mouse button from one point to an element or point.

Starts at (from_x, from_y) in screenshot pixels; ends at ref, or at x and y.

Parameters:

Name	Type	Description	Default
from_x	int	Start, horizontal, in screenshot pixels.	required
from_y	int	Start, vertical, in screenshot pixels.	required
ref	str | None	Element ref to drop on.	None
x	int | None	End, horizontal, in screenshot pixels (with y).	None
y	int | None	End, vertical, in screenshot pixels (with x).	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_left_mouse_down(tab_id=None, intent=None, ctx=None) async

Press and hold the left mouse button where the mouse is.

Parameters:

Name	Type	Description	Default
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_left_mouse_up(tab_id=None, intent=None, ctx=None) async

Release the left mouse button where the mouse is.

Parameters:

Name	Type	Description	Default
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_list_tabs(intent=None, ctx=None) async

List the open tabs with their tabId, title and URL.

Parameters:

Name	Type	Description	Default
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_middle_click(ref=None, x=None, y=None, modifiers=None, tab_id=None, intent=None, ctx=None) async

Middle-click an element or a point (often opens a link in a new tab).

Target an element with ref (preferred), or with x and y in screenshot pixels.

Parameters:

Name	Type	Description	Default
ref	str | None	Element ref such as "ref_12".	None
x	int | None	Horizontal position in screenshot pixels (with y).	None
y	int | None	Vertical position in screenshot pixels (with x).	None
modifiers	str | None	Keys to hold.	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_mouse_move(ref=None, x=None, y=None, tab_id=None, intent=None, ctx=None) async

Move the mouse to an element or a point without clicking.

Use with browser_left_mouse_down and browser_left_mouse_up for drags that need intermediate steps.

Parameters:

Name	Type	Description	Default
ref	str | None	Element ref such as "ref_12".	None
x	int | None	Horizontal position in screenshot pixels (with y).	None
y	int | None	Vertical position in screenshot pixels (with x).	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_navigate(url, tab_id=None, intent=None, ctx=None) async

Open a URL in the browser, or go "back", "forward" or "reload".

A URL without a scheme gets https://. Only http and https URLs can be opened. Opens a tab first if none is open. Refs from before the navigation stop working; read the page again.

Parameters:

Name	Type	Description	Default
url	str	The URL, or "back", "forward" or "reload".	required
tab_id	int | None	Tab to use (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_new_tab(url=None, intent=None, ctx=None) async

Open a new tab, optionally at a URL, and make it the active tab.

Parameters:

Name	Type	Description	Default
url	str | None	URL to open in the new tab.	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_read_console(tab_id=None, intent=None, ctx=None) async

Read the page's console messages since the last read (opt-in).

Parameters:

Name	Type	Description	Default
tab_id	int | None	Tab to read (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_read_network(tab_id=None, intent=None, ctx=None) async

List the page's network requests since the last read (opt-in).

Parameters:

Name	Type	Description	Default
tab_id	int | None	Tab to read (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_read_page(filter='interactive', depth=15, ref=None, tab_id=None, intent=None, ctx=None) async

Read the page as an accessibility tree, with a [ref_N] tag on each element.

Pass a ref to the action tools to act on that element. Refs stay valid until the tab navigates or the element is removed; a stale ref gives an error telling you to read the page again. "interactive" (default) lists links, buttons and form fields; "all" adds headings, images, text and landmarks. Covers the whole page, not just the visible part.

Parameters:

Name	Type	Description	Default
filter	Literal['interactive', 'all']	"interactive" (default) or "all".	'interactive'
depth	int	Maximum nesting depth, 1-50 (default 15).	15
ref	str | None	Read only the subtree under this ref.	None
tab_id	int | None	Tab to read (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_right_click(ref=None, x=None, y=None, modifiers=None, tab_id=None, intent=None, ctx=None) async

Right-click an element or a point (opens a context menu).

Target an element with ref (preferred), or with x and y in screenshot pixels.

Parameters:

Name	Type	Description	Default
ref	str | None	Element ref such as "ref_12".	None
x	int | None	Horizontal position in screenshot pixels (with y).	None
y	int | None	Vertical position in screenshot pixels (with x).	None
modifiers	str | None	Keys to hold, such as "shift".	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_run_script(code, tab_id=None, intent=None, ctx=None) async

Run a Python script against the browser with Playwright (opt-in).

For multi-step work the other tools make slow, such as extracting a whole table or looping over pages. The script runs in a separate process, with these names ready to use (Playwright's async API, so use await):

• page: the tab (await page.title(), await page.locator("table").inner_text())
• context: the browser context
• await screenshot(): capture the tab; the image is returned with the result
• await read_page(): the accessibility tree with refs other tools accept

print() output and the value of a final expression are returned. Variables persist between calls in the same session. A script that runs longer than DPTTOOLS_BROWSER_SCRIPT_TIMEOUT_S (60 s) is stopped and the variables are lost. The script is not network-contained: connections it opens itself are not checked. The browser's own traffic is (in cdp mode, only in the tabs this server manages).

Parameters:

Name	Type	Description	Default
code	str	Python code; top-level await is allowed.	required
tab_id	int | None	Tab bound to page (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_screenshot(tab_id=None, intent=None, ctx=None) async

Take a screenshot of the visible part of the page.

Prefer browser_read_page or browser_get_page_text to read a page; a screenshot is for checking layout or visual state. x/y arguments of the other tools are in this screenshot's pixels.

Parameters:

Name	Type	Description	Default
tab_id	int | None	Tab to capture (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_scroll(scroll_direction, scroll_amount=3, ref=None, x=None, y=None, tab_id=None, intent=None, ctx=None) async

Scroll the page, or the scrollable area under an element or point.

Without a target, scrolls at the centre of the page. Use browser_scroll_to to bring a known element into view.

Parameters:

Name	Type	Description	Default
scroll_direction	Literal['up', 'down', 'left', 'right']	up, down, left or right.	required
scroll_amount	int	1-10 steps of about 100 pixels (default 3).	3
ref	str | None	Element ref to scroll within.	None
x	int | None	Horizontal position in screenshot pixels (with y).	None
y	int | None	Vertical position in screenshot pixels (with x).	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_scroll_to(ref, tab_id=None, intent=None, ctx=None) async

Scroll an element into view.

Parameters:

Name	Type	Description	Default
ref	str	Element ref such as "ref_12".	required
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_switch_tab(tab_id, intent=None, ctx=None) async

Make another tab the active tab.

Parameters:

Name	Type	Description	Default
tab_id	int	The tab to switch to.	required
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_triple_click(ref=None, x=None, y=None, modifiers=None, tab_id=None, intent=None, ctx=None) async

Triple-click an element or a point (for example to select a paragraph).

Target an element with ref (preferred), or with x and y in screenshot pixels.

Parameters:

Name	Type	Description	Default
ref	str | None	Element ref such as "ref_12".	None
x	int | None	Horizontal position in screenshot pixels (with y).	None
y	int | None	Vertical position in screenshot pixels (with x).	None
modifiers	str | None	Keys to hold.	None
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_type(text, tab_id=None, intent=None, ctx=None) async

Type text into the focused element, as if on a keyboard.

Click a field first to focus it, or use browser_form_input to set a field's value by ref.

Parameters:

Name	Type	Description	Default
text	str	The text to type.	required
tab_id	int | None	Tab to act in (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_wait(duration, tab_id=None, intent=None, ctx=None) async

Wait a number of seconds (at most 30), for a page to finish loading or animating.

Parameters:

Name	Type	Description	Default
duration	float	Seconds to wait, at most 30.	required
tab_id	int | None	Tab to report on (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

browser_zoom(x0, y0, x1, y1, tab_id=None, intent=None, ctx=None) async

Capture one region of the page, enlarged, to read small text or details.

The region is a rectangle in screenshot pixels, from (x0, y0) to (x1, y1).

Parameters:

Name	Type	Description	Default
x0	int	Left edge. y0: Top edge. x1: Right edge. y1: Bottom edge.	required
tab_id	int | None	Tab to capture (default: the active tab).	None
intent	str | None	Optional note on why you are doing this (logged only).	None

fetch_webpage_rendered(url, max_length=10000, offset=0, format='text', include_assets=False) async

Fetch a web page in a real browser, running its JavaScript, and return its content.

Use this when fetch_webpage returns little or no text, or says likely_js_rendered: true: single-page apps and client-rendered pages only have content after their scripts run. Slower than fetch_webpage (seconds, not milliseconds), so try that first.

Returns the same JSON object as fetch_webpage (url, final_url, status, title, format, extractor, text, truncated, total_chars, offset, next_offset, has_more, plus "rendered": true). Each call uses a fresh, credential-free browser context that is closed afterwards; the browser's network policy applies (private addresses refused).

Parameters:

Name	Type	Description	Default
url	str	The page to fetch (http or https).	required
max_length	int	Maximum characters of text to return (default 10000).	10000
offset	int	Character offset to start from, for long pages (default 0).	0
format	Literal['text', 'markdown', 'html']	"text" (default), "markdown" or "html".	'text'
include_assets	bool	Add the page's image and link references (default False).	False

get_browser_state(session_key=DEFAULT_SESSION)

Structured state of one browser session, for a future native adapter.

A plain Python function, not an MCP tool.

make_browser_server(tools=None, enable=None)

Build the browser server.

Both profiles also register fetch_webpage_rendered.

Parameters:

Name	Type	Description	Default
tools	str | None	"core" (18 tools) or "full" (27). Defaults to DPTTOOLS_BROWSER_TOOLS.	None
enable	Iterable[str] | None	Opt-in members to add (javascript_exec, file_upload, read_console, read_network, run_script). Defaults to DPTTOOLS_BROWSER_ENABLE.	None