Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
CHROME_PATHNoPath to the Chrome/Chromium binary used first in browser discovery.
FIREFOX_PATHNoPath to the Firefox binary used for browser discovery, after --firefox-path.

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

Browser Control MCP Server Instructions:

  • Browsers: every instance runs Chrome (CDP) or Firefox (WebDriver BiDi + RDP debugger). Pick it with open_instance's browser ("chrome" or "firefox"); the default instance uses the server's --browser flag (Chrome unless configured). Choose Firefox only when the user asks for it or Chrome is unavailable. An instance never changes browser: every command on it uses its protocol.

  • Instances: a 'default' instance always exists and is launched lazily on first use. open_instance with a unique 'label' creates another one (the label becomes its instance_id). Pass instance_id to address it (omit it for the default). list_instances shows each instance's browser and capabilities; close_instance stops one.

  • Tabs: open_tab, list_tabs, switch_tab, close_tab. Every tool accepts tab_id; omit it for the active tab, which is the one the browser shows (open_tab makes its new tab active; a tab a click opens is not, the reply names it). Console logs, network traffic, issues (get_issues: blocked cookies, CORS, CSP, mixed content) and breakpoints are kept per tab. Downloads are saved per instance: an action that starts one names the saved file, and list_downloads lists them.

  • Pages: snapshot outlines the page (roles, names, states, refs such as e12); find_in_snapshot searches that outline on large pages; get_css_styles says why an element looks as it does (matched rules, overridden declarations, computed values). The selector of click_element, fill_input, scroll and wait_for takes a ref, CSS, or 'host >>> inner' to reach into open shadow roots and same-origin iframes. Frames of another origin are in the outline too: their iframe line says [frame=f2], their refs look like f2e5, and 'f2 >>> css' selects inside them. click_element, hover, drag, fill_input, fill_form and press_key then wait up to 1 s for the page to settle (DOM quiet, the requests they started finished) and say how it reacted; wait_for waits for text, an element or a URL beyond that.

  • Browser limits: WebMCP, cookie import and launch features are Chrome only; performance metrics and profiling are partial on Firefox (Web Performance APIs, the reply says what is missing); Firefox WebSocket frames and page errors need its debugger port. A tool an instance cannot serve fails with an error naming the tool and the browser; nothing is sent to the browser.

  • Debugging (listed with --tool-groups debug, except resume, which is always listed): set_breakpoint, remove_breakpoint, resume, step_over, step_into, step_out, call_stack (frames, why it paused, what was thrown; on Chrome each frame's scopes), evaluate_on_call_frame (in any frame of the stack; on Chrome 156+ in one of its scopes), pause_on_exceptions and search_scripts work on Chrome and Firefox; pause_on_load is Chrome only for now. On Firefox they use the Firefox debugger port, enabled unless the server runs with --no-firefox-debugger; set breakpoints by script URL.

  • Firefox sessions: a Firefox allows one automation session at a time. Always stop Firefox instances with close_instance or stop_browser when done.

  • Tool groups: some tools are listed only when the server runs with --tool-groups: debug (the debugger tools above but resume, which is always listed), storage (cookies, web_storage), files (upload_file, save_pdf, record_video), raw (send_cdp_command, send_bidi_command, send_rdp_request, get_custom_events), perf (get_performance_metrics, profile_page_performance, audit_page, lighthouse_report), emulation (emulate), network (mock_route, list_routes, remove_route, set_offline), or all. A tool of a group that is off fails naming the flag.

  • Cookie import: with --allow-cookie-import, navigate, open_instance and restart_browser accept copy_cookies: true (Chrome only). Always ask the user before copying their real cookies.

  • Proxy: with --proxy-server, instances use the proxy and enable_proxy_auth answers proxy (407) authentication challenges.

  • WebMCP: with --enable-webmcp, Chrome instances expose webmcp_list_tools, webmcp_invoke_tool, webmcp_get_invocation, webmcp_list_invocations and webmcp_cancel_invocation.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
capture_screenshotA

Screenshot of the tab's viewport, of the whole page with full_page, or of one element with selector (at most 16384 CSS pixels per side; a larger capture gets a note). To find elements to act on, prefer 'snapshot'.

click_elementA

Clicks an element with real mouse input after scrolling it into view; waits up to 2 s for a CSS selector's element to appear or be enabled, and fails without clicking when it is hidden, covered (naming the overlay) or disabled. A dialog or breakpoint the click triggers is noted in the reply ({dialog} or {paused, location}), not an error: continue with handle_dialog or resume (evaluate_on_call_frame, with --tool-groups debug, reads the paused frame).

fill_inputA

Types into a text field, textarea or contenteditable, replacing its content (or after it with append), key by key so the page's handlers run (~1 ms per character); picks the option(s) named; sets a date, time, range or colour input (YYYY-MM-DD, HH:MM, a number, #rrggbb). Fails without typing on disabled, read-only, non-text or unfocusable elements and when the field rejects the text; notes a reformatted value. For several fields at once use fill_form.

fill_formA

Fills several fields in one call, in order: text fields and s as fill_input does; a checkbox or radio takes 'true' or 'false' and is clicked only when its state differs. Returns each field's outcome (filled, selected, checked, unchecked, unchanged), never the values; stops at the first failing field, naming it and what was done.

press_keyA

Presses one key, with modifiers (Control+a, Shift+Tab), as a user would, in the element given (focused first) or the focused one; the browser's default action runs (Enter submits, Tab moves the focus). With Control, Alt or Meta held nothing is typed. To type text use fill_input. A dialog or breakpoint it causes is noted, as for click_element.

hoverA

Moves the mouse over an element (scrolled into view; fails when hidden or covered) so hover menus, tooltips and :hover styles appear.

dragA

Drags an element onto another with the mouse, for sortable lists, boards, sliders and HTML5 drag and drop: presses on 'from' (scrolled into view; waits up to 2 s for it to appear or be enabled; fails when hidden, covered or disabled), moves in steps to the centre of 'to' (which must be in the viewport) and releases. Firefox simulates HTML5 drag and drop with script events.

evaluate_jsA

Evaluates JavaScript in the page and returns its value (promises awaited; top-level await works in code up to 64 KB that parses, the last statement giving the value; other code runs as written): {value, type, subtype?, description?, preview?}. value is the JSON form; a Map, Set, typed array, Error, cycle or throwing getter gets a bounded preview (preview: true; a Map as [key, value] pairs, a Set or typed array as items, an Error as {name, message, stack}, '[Circular]', '[Thrown: message]') that description names (Map(2), TypeError: bad); functions, nodes and symbols give null, described (a function's source). Cut over 100000 characters (truncated: true). An exception fails with its message, and its 1-based line and column when they are in the expression. user_gesture: true lets the expression call APIs that need a user action (requestFullscreen, clipboard writes, window.open past the popup blocker); off by default, as the page then gets that power. In a paused frame use evaluate_on_call_frame (--tool-groups debug). Chrome stops a script after 8 s; Firefox cannot (close a frozen tab with close_tab).

navigateA

Loads a URL in the tab, or moves back or forward in its history, and waits for load (at most 30 s; a breakpoint or dialog while loading fails at once saying so). Returns {url (after redirects), tab_id, browser, status?, notes?}. A network error, a download or a page behind HTTP authentication (log in with http://user:password@host/path) fails with 'Navigation failed: ()'. With --local only local addresses are allowed.

inspect_domA

Returns the page's HTML (open shadow roots as , same-origin iframes appended after ; at most 100000 characters), or with 'query' the first match and its context. To find elements to act on, prefer 'snapshot'.

snapshotA

Outlines the page to act on it: one line per element with a role (button, link, textbox, heading...), name, states, value and a ref ([ref=e12]), indented under its parent; an invalid field shows [invalid] [error='why'], a its first 25 options (pick one with fill_input); through open shadow roots and iframes (another origin's frame is [frame=f2], refs f2e5; selector 'f2' outlines it alone); hidden elements left out, passwords never shown; at most 50000 characters (find_in_snapshot searches it whole). Refs work as the selector of the input tools until the page navigates. Same on Chrome and Firefox.

find_in_snapshotA

Searches the whole 'snapshot' outline (never cut) and returns only the matching lines under their ancestors, with their refs (at most 20 matches). Cheaper than 'snapshot' on a large page.

reloadA

Reloads the tab and waits for load (at most 30 s; a page that pauses at a breakpoint or opens a dialog while loading fails at once saying so). Returns the same shape as 'navigate'.

scrollA

Scrolls the window by pixels or viewport heights, or brings an element into view; wheel: true sends a real mouse wheel event instead, for a canvas or map. Returns the window positions {before, after, element_in_view?} and says when nothing moved (on a page that scrolls an inner element, pass a selector inside it).

wait_forA

Waits until every condition given holds: visible text appears or disappears (open shadow roots and same-origin iframes included), an element reaches a state, or the URL contains a text; checks every 100 ms. Returns the time waited; on timeout it fails naming what is missing. A dialog or debugger pause ends it at once.

handle_dialogA

Accepts or dismisses the JavaScript dialog (alert, confirm, prompt, beforeunload) open on the tab. While one is open, tools that run page code fail naming it. Returns {accepted, dialog}; fails when none is open.

resumeA

Resumes a page paused in the debugger (a breakpoint, a step, an exception or its own debugger statement). Returns {paused, location: {url, line_number, column_number} | null} (0-based): paused only if it stopped again within 250 ms (another breakpoint).

restart_browserA

Restarts an instance's browser (closing its tabs), optionally with another proxy or presets. A browser the server attached to (not launched) is not restarted: the call fails saying so.

stop_browserA

Stops an instance's browser and closes its tabs; other instances keep running. A browser the server attached to (not launched) is only disconnected.

open_instanceA

Starts a new browser instance, Chrome or Firefox, with its own profile; its 'label' becomes the instance_id other tools take. Fails in --user-profile mode.

list_instancesB

Lists the instances: id, browser, capabilities, label, host, port (0 until a Chrome the server launches has picked one), profile_dir, features, is_default.

close_instanceA

Stops an instance: other instances are removed; 'default' is stopped and relaunched on its next use.

open_tabA

Opens a tab (launching the instance if needed; a fresh instance's untouched blank start tab is used, once, instead of opening a second one), makes it the active tab in front, and waits for 'url' to load. Returns {tab_id, target_id, url, label}; a network error fails naming the tab, which stays open.

list_tabsA

Lists the instance's tabs: {active_tab_id, tabs: [{tab_id, label, target_id, url}]}.

close_tabA

Closes a tab (default: the active one); the most recently active open tab (else the newest) becomes active and is brought to the front. Returns {closed_tab_id, active_tab_id}.

switch_tabA

Makes a tab the target of the tools that omit tab_id, and brings it to the foreground unless 'activate' is false.

list_downloadsA

Lists the files the instance's pages downloaded, oldest first (id, url, file_name, path once complete, state: in_progress, completed or canceled, sizes, tab_id), and their directory (a folder of --downloads-dir named after the instance id, else the instance's temporary profile, deleted with it). An action that starts a download also says where the file went.

get_network_logsA

Lists the tab's HTTP requests (id, method, URL, status, type; the last 3 navigations, oldest first) and WebSocket frames and closes, with filters. request_id or include_details gives headers and bodies (cut at 64000 characters; a body over 2 MB is omitted, with its size). A redirect chain is one request, found by any hop's URL; its details list each hop's status and Location. Request bodies and the values of headers other than standard ones known to hold no credential (an app's own X-... headers included) are redacted unless include_sensitive_headers.

get_console_logsA

Lists the tab's console messages and uncaught exceptions, oldest first, one line each: [level] text @ url:line (lines from 1; objects previewed, repeats folded, stacks indented); on Chrome an uncaught error's cause chain follows it (Caused by: lines); include_details gives {messages, total, truncated, notes?} as JSON. Keeps the last 1000 (10000 characters each); cleared when the tab moves to another site. For problems the browser diagnosed (blocked cookies, CORS, CSP) use get_issues.

get_issuesA

Lists the problems the browser diagnosed in the tab that the console hides or words vaguely: blocked or warned cookies and why, CORS and Content-Security-Policy blocks, mixed content, deprecated features, and on Chrome every code of its DevTools Issues panel (form fields without id, name or label, LazyLoadImageIssue...). One line each, oldest first: [code] title: summary @ url [xN] (a title for the common Chrome codes; N distinct reports, one per element or request), then on Chrome its elements (selector [ref=eN], refs as snapshot's, at most 10). For console messages use get_console_logs. Firefox has no Issues panel: its security and deprecation console messages are read as issues (cookies, CSP, mixed content, CORS, DeprecationIssue; needs its debugger port).

get_css_stylesA

Explains why an element looks as it does: the CSS rules matching it, highest priority first (style attribute, then rules), each with selector, stylesheet URL (the page's for an inline ), 0-based line and column, enclosing at-rules (@media, @container, @layer, @supports) and declarations marked important, invalid or overridden; its pseudo-elements; and the computed values of the declared properties. Options add the ancestors' rules (nearest first) and the browser's, or narrow to some properties (declarations included). Firefox reads them with its inspector (needs its debugger port).

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.8/5.0

Scored across 31 tools

Disambiguation4/5

Most tools have clearly distinct purposes (click vs fill vs press_key vs hover vs drag; snapshot vs inspect_dom; console vs issues vs network logs). The main blur is among lifecycle tools: stop_browser, restart_browser, and close_instance overlap in meaning, and fill_input vs fill_form require reading descriptions to separate. These are minor compared with the strongly partitioned rest of the surface.

Naming Consistency4/5

Dominant snake_case verb_noun pattern (capture_screenshot, open_tab, get_network_logs, list_downloads) with predictable prefixes for read/list/create lifecycle. Deviations exist: bare verbs (hover, drag, scroll, reload, resume, navigate) and a lone noun (snapshot), but the grouping remains readable and predictable.

Tool Count3/5

31 tools is heavy for a browser server, though the breadth (interaction, DOM, network, console, CSS, tabs, instances, downloads, debugging) justifies much of it. Some consolidation is possible - stop_browser/restart_browser vs close_instance, and find_in_snapshot as a helper to snapshot - so the count is borderline rather than well-scoped.

Completeness4/5

Coverage is unusually thorough: navigation, snapshot/DOM inspection, full input simulation, network and console logs, browser-diagnosed issues, CSS inspection, dialogs, debugger pauses, and instance/tab/download management. Gaps remain around file uploads, cookie/storage/state management, and network interception or viewport/device emulation, which agents will occasionally need.

Maintenance

ActivityActive
ResponsivenessNo recent community issues