Browser MCP

A fast, lightweight MCP server that empowers LLMs with browser automation via Puppeteer’s structured accessibility data, featuring optional vision mode for complex visual understanding and flexible, cross-platform configuration.

Browser Use MCP Server

NPM Downloads smithery badge codecov

Install MCP Server

A fast, lightweight Model Context Protocol (MCP) server that empowers LLMs with browser automation via Puppeteer’s structured accessibility data, featuring optional vision mode for complex visual understanding and flexible, cross-platform configuration.

Key Features

  • ⚡ Fast & lightweight. Utilizes Puppeteer's label index, not pixel-based input and accessibility DOM tree.
  • 👁️ Vision Mode Support. Optional visual understanding capabilities for complex layouts and visual elements when structured data isn't sufficient.
  • 🤖 LLM-optimized. No vision models needed, operates purely on structured data, less context reducing context token usage.
  • 🧩 Flexible Runtime Configuration. Customize viewport size, coordinate system factors, and User-Agent at runtime via HTTP headers.
  • 🌐 Cross-Platform & Extensible. Support for remote and local browsers, the use of a custom browser engine.

Requirements

  • Node.js 18 or newer
  • VS Code, Cursor, Windsurf, Claude Desktop or any other MCP client

Getting started

Local (Stdio)

First, install the Browser MCP server with your client. A typical configuration looks like this:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "@agent-infra/mcp-server-browser@latest"
      ]
    }
  }
}

You can also install the Browser MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '{"name":"browser","command":"npx","args":["@agent-infra/mcp-server-browser@latest"]}'

After installation, the Browser MCP server will be available for use with your GitHub Copilot agent in VS Code.

Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx @agent-infra/mcp-server-browser. You can also verify config or add command like arguments via clicking Edit.

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "@agent-infra/mcp-server-browser@latest"
      ]
    }
  }
}

Follow Windsuff MCP documentation. Use following configuration:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "@agent-infra/mcp-server-browser@latest"
      ]
    }
  }
}

Follow the MCP install guide, use following configuration:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "@agent-infra/mcp-server-browser@latest"
      ]
    }
  }
}

Remote (SSE / Streamable HTTP)

At the same time, use --port $your_port arg to start the browser mcp can be converted into SSE and Streamable HTTP Server.

# normal run remote mcp server
npx @agent-infra/mcp-server-browser --port 8089

# run with DISPLAY environment for VNC or other virtual display
DISPLAY=:0 npx @agent-infra/mcp-server-browser --port 8089

You can use one of the two MCP Server remote endpoint:

  • Streamable HTTP(Recommended): http://127.0.0.1::8089/mcp
  • SSE: http://127.0.0.1::8089/sse

And then in MCP client config, set the url to the SSE endpoint:

{
  "mcpServers": {
    "browser": {
      "url": "http://127.0.0.1::8089/sse"
    }
  }
}

url to the Streamable HTTP:

{
  "mcpServers": {
    "browser": {
      "type": "streamable-http", // If there is MCP Client support
      "url": "http://127.0.0.1::8089/mcp"
    }
  }
}

In-memory call

If your MCP Client is developed based on JavaScript / TypeScript, you can directly use in-process calls to avoid requiring your users to install the command-line interface to use Browser MCP.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';

// type: module project usage
import { createServer } from '@agent-infra/mcp-server-browser';
// commonjs project usage
// const { createServer } = await import('@agent-infra/mcp-server-browser')

const client = new Client(
  {
    name: 'test browser client',
    version: '1.0',
  },
  {
    capabilities: {},
  },
);

const server = createServer();
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();

await Promise.all([
  client.connect(clientTransport),
  server.connect(serverTransport),
]);

// list tools
const result = await client.listTools();
console.log(result);

// call tool
const toolResult = await client.callTool({
  name: 'browser_navigate',
  arguments: {
    url: 'https://www.google.com',
  },
});
console.log(toolResult);

Configuration

Browser MCP server supports following arguments. They can be provided in the JSON configuration above, as a part of the "args" list:

> npx @agent-infra/mcp-server-browser@latest -h
  -V, --version              output the version number
  --browser <browser>        browser or chrome channel to use, possible values: chrome, edge, firefox.
  --cdp-endpoint <endpoint>  CDP endpoint to connect to, for example "http://127.0.0.1:9222/json/version"
  --ws-endpoint <endpoint>   WebSocket endpoint to connect to, for example "ws://127.0.0.1:9222/devtools/browser/{id}"
  --executable-path <path>   path to the browser executable.
  --headless                 run browser in headless mode, headed by default
  --host <host>              host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
  --port <port>              port to listen on for SSE and HTTP transport.
  --proxy-bypass <bypass>    comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"
  --proxy-server <proxy>     specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"
  --user-agent <ua string>   specify user agent string
  --user-data-dir <path>     path to the user data directory.
  --viewport-size <size>     specify browser viewport size in pixels, for example "1280, 720"
  --output-dir <path>        path to the directory for output files
  --vision                   Run server that uses screenshots (Aria snapshots are used by default)
  -h, --help                 display help for command

Runtime Configuration

The browser runtime requires configuration for Viewport Size, Vision Model Coordinate Factors, and User Agent. These can be passed through corresponding HTTP headers:

HeaderDescription
x-viewport-sizeBrowser viewport size, format: width,height separated by comma
x-vision-factorsVision model coordinate system factors, format: x_factor,y_factor separated by comma
x-user-agentUser Agent string, defaults to system User Agent if not specified

Note: Header names are case-insensitive.

Example:

x-viewport-size: 1920,1080
x-vision-factors: 1.0,1.0
x-user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36

Docker

We have unified the deployment of VNC and MCP under a single URL endpoint, The Dockerfile and DockerHub image will be published together! video

API

Tools

Tool NameDescriptionParameters
browser_clickClick an element on the page, before using the tool, use browser_get_clickable_elements to get the index of the element, but not call browser_get_clickable_elements multiple timesindex (number, optional): Index of the element to click
browser_closeClose the browser when the task is done and the browser is not needed anymoreNone
browser_close_tabClose the current tabNone
browser_evaluateExecute JavaScript in the browser consolescript (string, required): JavaScript code to execute
browser_form_input_fillFill out an input field, before using the tool, Either 'index' or 'selector' must be providedselector (string, optional): CSS selector for input fieldindex (number, optional): Index of the element to fillvalue (string, required): Value to fill
browser_get_clickable_elementsGet the clickable or hoverable or selectable elements on the current page, don't call this tool multiple timesNone
browser_get_download_listGet the list of downloaded filesNone
browser_get_htmlDeprecated, please use browser_get_markdown insteadNone
browser_get_markdownGet the markdown content of the current pageNone
browser_get_textGet the text content of the current pageNone
browser_go_backGo back to the previous pageNone
browser_go_forwardGo forward to the next pageNone
browser_hoverHover an element on the page, Either 'index' or 'selector' must be providedindex (number, optional): Index of the element to hoverselector (string, optional): CSS selector for element to hover
browser_navigateNavigate to a URLurl (string, required):
browser_new_tabOpen a new taburl (string, required): URL to open in the new tab
browser_press_keyPress a key on the keyboardkey (string, required): Name of the key to press or a character to generate, such as Enter, Tab, Escape, Backspace, Delete, Insert, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, ArrowLeft, ArrowRight, ArrowUp, ArrowDown, PageUp, PageDown, Home, End, ShiftLeft, ShiftRight, ControlLeft, ControlRight, AltLeft, AltRight, MetaLeft, MetaRight, CapsLock, PrintScreen, ScrollLock, Pause, ContextMenu
browser_read_linksGet all links on the current pageNone
browser_screenshotTake a screenshot of the current page or a specific elementname (string, optional): Name for the screenshotselector (string, optional): CSS selector for element to screenshotindex (number, optional): index of the element to screenshotwidth (number, optional): Width in pixels (default: viewport width)height (number, optional): Height in pixels (default: viewport height)fullPage (boolean, optional): Full page screenshot (default: false)highlight (boolean, optional): Highlight the element
browser_scrollScroll the pageamount (number, optional): Pixels to scroll (positive for down, negative for up), if the amount is not provided, scroll to the bottom of the page
browser_selectSelect an element on the page with index, Either 'index' or 'selector' must be providedindex (number, optional): Index of the element to selectselector (string, optional): CSS selector for element to selectvalue (string, required): Value to select
browser_switch_tabSwitch to a specific tabindex (number, required): Tab index to switch to
browser_tab_listGet the list of tabsNone
browser_vision_screen_captureTake a screenshot of the current page for vision modeNone
browser_vision_screen_clickClick left mouse button on the page with vision and snapshot, before calling this tool, you should call browser_vision_screen_capture first only once, fallback to browser_click if failedfactors (array, optional): Vision model coordinate system scaling factors [width_factor, height_factor] for coordinate space normalization. Transformation formula: x = (x_model * screen_width * width_factor) / width_factor y = (y_model * screen_height * height_factor) / height_factor where x_model, y_model are normalized model output coordinates (0-1), screen_width/height are screen dimensions, width_factor/height_factor are quantization factors, If the factors are unknown, leave it blank. Most models do not require this parameter.x (number, required): X coordinatey (number, required): Y coordinate

Resources

Resource NameURI PatternDescriptionMIME Type
Browser console logsconsole://logstext/plain
Browser Downloadsdownload://{name}Automatic identification based on file extension
Browser Screenshotsscreenshot://{name}Automatic identification based on file extension

Developement

Access http://127.0.0.1:6274/:

npm run dev

Extended CLI Entry

#!/usr/bin/env node

const {
  BaseLogger,
  setConfig,
  addMiddleware,
} = require('@agent-infra/mcp-server-browser/dist/request-context.cjs');

class CustomLogger extends BaseLogger {
  info(...args) {
    console.log('custom');
    console.log(...args);
  }
}

addMiddleware((req, res, next) => {
  console.log('req', req.headers);
  next();
});

setConfig({
  logger: new CustomLogger(),
});

// start server
require('@agent-infra/mcp-server-browser/dist/index.cjs');

Related Servers