Skip to main content
Glama

browser-mcp is a Model Context Protocol server that extends any MCP-capable client — Claude, opencode, and friends — with full control over a real Google Chrome window. Through a tiny Chrome extension, the agent navigates pages, clicks, types, screenshots, and inspects the live DOM of a session that already has your logins, cookies, and extensions loaded.

Quick start

npm install          # 1. install dependencies
npm start            # 2. launch the MCP server (WebSocket bridge on ws://127.0.0.1:9333)

Then load the extension:

  1. Open chrome://extensions in Chrome and enable Developer mode.

  2. Click Load unpacked and select the extension/ folder from this repo.

  3. Point your MCP client at the server:

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/absolute/path/to/browser-mcp/server.js"]
    }
  }
}

That's it. The extension auto-connects to the bridge — no headless browser, no driver process, no screenshots-of-a-screenshot. Your AI operates the very Chrome window on your desk.

Related MCP server: mcp-browser-server

Tools

Tool

Does what

browser_navigate

Open a URL in the controlled tab, returns the page snapshot

browser_snapshot

Accessibility tree of the page, every element tagged with a ref

browser_click

Click an element by ref

browser_type

Type into a textbox / textarea, optionally press Enter

browser_select_option

Pick values from a dropdown

browser_press_key

Send keys: Enter, Escape, ArrowDown, Tab, Meta+K, …

browser_hover

Hover an element (reveal hover menus)

browser_wait

Pause N seconds for transitions and animations

browser_back / browser_forward

History navigation

browser_screenshot

Grab a PNG of the page

browser_get_console_logs

Console messages and page errors since the last call

browser_close

Close the controlled tab and detach

Interaction tools take a ref from the latest browser_snapshot — so a typical agent loop is: snapshot → act → snapshot → act, exactly like a human looking at the page.

How it works

                 stdio (JSON-RPC)               WebSocket 127.0.0.1:9333
  MCP client   ─────────────────▶  server.js  ─────────────────────────▶  Chrome
  (Claude,     ◀─────────────────  MCP tools    ◀────────────────────────  extension
   opencode…)       results           │ bridge                              │
                                     └──────────── 1. CDP (chrome.debugger) ─┘
                                                  2. accessibility snapshot

Three moving parts, one goal:

  1. server.js — the MCP server. Exposes the 13 tools over stdio to any MCP client and runs an embedded WebSocket bridge for talking to the extension.

  2. The bridge — a localhost-only listener on 127.0.0.1:9333 that multiplexes requests/responses, with per-call timeouts and automatic reconnection.

  3. The extension (extension/) — an MV3 service worker connected to the bridge. It drives the active tab over the Chrome DevTools Protocol (chrome.debugger), renders accessibility snapshots, and reports console output back.

Because the browser machinery lives entirely in the extension, the MCP surface stays clean and standard — and because the extension keeps your real session, the agent gets your real state.

Features

  • Controls the browser session you're already logged into — cookies, extensions, and multi-account setups just work.

  • Compact accessibility snapshots — role, name, value, checked-state, and a stable ref for every interactive element.

  • full console insight — browser_get_console_logs surfaces console.log, warnings, and page errors, which is a huge debugging superpower.

  • Multi-display aware — on macOS the server auto-detects your displays and targets your chosen window position (usable on Linux/Windows too, just with primary-display default).

  • Zero browser-driver setup — no Playwright binary downloads or npx playwright install to run the server; Playwright is used only in the test harness.

  • Standards-first — built on the official MCP TypeScript SDK with Zod-validated inputs.

Configuration

Flags for server.js:

Flag

Default

Description

--port <n>

9333

WebSocket bridge port (must match the extension's endpoint)

--display <n>

1

Physical display to target (1-based, prefers secondary displays on macOS)

--debug

off

Verbose diagnostics on stderr

node server.js --port 9333 --display 2 --debug

Debug mode prints bridge status, connection events, and per-tool diagnostics to stderr; JSON-RPC traffic flows on stdout.

Requirements

Component

Requirement

Node.js

≥ 18

Browser

Google Chrome / Chromium (MV3 extension support)

OS

macOS fully supported (auto multi-display targeting); others fall back to the primary display

MCP client

Any host running external MCP servers over stdio

Testing

node test-client.mjs   # scripted stdio client exercising the full tool flow
node e2e.mjs            # Playwright-launched Chrome with the extension pre-loaded

Project structure

browser-mcp/
├── server.js           # MCP server, tool definitions, WebSocket bridge
├── extension/          # Chrome MV3 extension (CDP-based tab automation)
│   ├── manifest.json   # extension manifest (permissions, service worker)
│   ├── background.js   # CDP attach, snapshot rendering, tool execution
│   ├── popup.html/.js  # status popup
│   ├── icons/          # 16/32/48/128 px
│   └── …
├── test-client.mjs     # MCP stdio smoke test
├── e2e.mjs             # end-to-end test with Playwright
├── package.json
└── README.md

License

MIT © 2026 Parithosh Varma

Available Tools

13 tools
browser_backGo backB

Navigate back in history.

Inputs: no named parameters.

browser_clickClickA

Click an element identified by its ref from the snapshot. After clicking, returns an updated snapshot.

Inputs: ref (required).

browser_closeClose tabB

Close the controlled Chrome tab and detach.

Inputs: no named parameters.

browser_forwardGo forwardB

Navigate forward in history.

Inputs: no named parameters.

browser_get_console_logsConsole logsA

Get console messages and page errors collected since the last call.

Inputs: no named parameters.

browser_hoverHoverA

Move the mouse over an element identified by ref (useful for hover menus).

Inputs: ref (required).

browser_navigateNavigateB

Open a URL in the Chrome tab controlled by the extension. Returns the page snapshot with element refs.

Inputs: url (required).

browser_press_keyPress keyB

Press a keyboard key, e.g. Enter, Escape, ArrowDown, Tab, Control+A, Meta+K.

Inputs: key (required).

browser_screenshotScreenshotB

Take a screenshot of the current page. Returns the image.

Inputs: no named parameters.

browser_select_optionSelect optionA

Select one or more options in a dropdown (combobox) identified by ref. Values are the option text or value.

Inputs: ref (required), values (required).

browser_snapshotSnapshotA

Return the current accessibility tree of the page with element refs. Elements are addressed by their ref in every other tool. Run this after every interaction.

Inputs: no named parameters.

browser_typeTypeA

Type text into a textbox/textarea identified by ref. Optionally press Enter after (submit=true) and get the updated snapshot.

Inputs: ref (required), text (required), submit.

browser_waitWaitA

Wait a number of seconds (for page transitions or animations).

Inputs: seconds (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool maps to a distinct action on the page: navigate/back/forward for history, snapshot vs screenshot for structure vs image, and click/type/select_option/press_key/hover for separate input modalities. The only superficially close pair, browser_snapshot and browser_screenshot, is clearly differentiated by their descriptions.

    Naming Consistency4/5

    All 13 tools share a uniform browser_ prefix and snake_case style, making the set highly predictable. Minor deviation: several names are bare nouns or adverbs (browser_snapshot, browser_back, browser_close) rather than verb_noun, but this stays readable and consistent within the domain.

    Tool Count5/5

    13 tools is right in the sweet spot for a browser automation surface, and every tool covers a genuinely needed operation (navigation, interaction, inspection, lifecycle). No redundant or filler tools are present.

    Completeness4/5

    Core browser workflows are fully covered: navigate, inspect, interact, capture, read console, and close. Minor gaps remain around explicit scrolling, tab/window management, file upload, and iframe or JS evaluation, though most can be worked around with press_key and repeated snapshots.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides AI models with full browser automation capabilities through Chrome. It enables navigation, interaction, screenshots, and complete DevTools access by bridging AI clients with a companion Chrome extension.
      99
      3 npm
      3
      Apache 2.0
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server that enables AI agents to control Chrome via DevTools CDP and accessibility trees, providing 21 tools for browser automation including tab management, navigation, interactions, and page capture.
      -