Skip to main content
Glama
Local Browser MCP

Local Browser MCP

by nolanbaxter

Local Browser MCP

CI License: MIT Node

A headless, agent-controllable real browser as an MCP server. It gives an agent (Claude Code, or any MCP client) a real Playwright browser pointed at your local dev servers — and any hosts you explicitly allow. Navigate, click, hover, fill, type, run JS, screenshot, snapshot the DOM, and read console/network, all over MCP.

The agent launches the browser, drives it headlessly, and it's torn down when the session ends. Because it normally only drives your own localhost, it can be given broad control without general-web-browsing risk; additional hosts are opt-in.

Install

Requires Node.js ≥ 20. The Chromium binary (~110 MB) is downloaded automatically on first install.

Add it to your MCP config (e.g. a project .mcp.json, your user config via claude mcp add, or your client's equivalent). npx runs it straight from this GitHub repo — no npm registry account needed (requires git on the machine):

{
  "mcpServers": {
    "local-browser": {
      "command": "npx",
      "args": ["-y", "github:NolanLT/local-browser-mcp"],
      "env": {
        "LOCAL_BROWSER_ALLOWED_HOSTS": "localhost,127.0.0.1"
      }
    }
  }
}

Restart your client. The tools appear with no other setup — MCP namespaces them under the server name, so they show up as local-browser: navigate, local-browser: click, and so on. (First run installs dependencies and downloads Chromium, then caches.)

If the package is also published to npm, you can swap the arg for the shorter ["-y", "local-browser-mcp"].

As a Claude Code plugin (GitHub marketplace)

/plugin marketplace add NolanLT/local-browser-mcp
/plugin install local-browser@local-browser-marketplace

The plugin's MCP server is the same npx invocation above.

Related MCP server: Secure Browser MCP

Configuration (environment variables)

Variable

Default

Purpose

LOCAL_BROWSER_ENGINE

chromium

chromium (recommended) | firefox | webkit

LOCAL_BROWSER_ALLOWED_HOSTS

localhost,127.0.0.1

Comma-separated navigation allowlist

LOCAL_BROWSER_ALLOW_ALL

false

true allows any http/https host (see Security)

LOCAL_BROWSER_SKIP_BROWSER_DOWNLOAD

—

1 to skip the Chromium download on install

LOCAL_BROWSER_HTTP_PORT

—

If set, run in HTTP mode on this port (else stdio)

LOCAL_BROWSER_HTTP_HOST

127.0.0.1

HTTP bind address; use 0.0.0.0 for a directly-hosted box

LOCAL_BROWSER_TOKEN

—

If set, HTTP requests need Authorization: Bearer <token>

Remote / connector mode (claude.ai web & mobile, Cowork, Desktop connectors)

stdio only reaches clients on the same machine. To use this from claude.ai (web/mobile), Cowork, or a Desktop custom connector, run it in HTTP mode and expose it over public HTTPS — Anthropic's cloud connects to your endpoint, so it must be reachable and authenticated.

⚠️ A public endpoint can drive a real browser, including eval. Always set LOCAL_BROWSER_TOKEN and keep a tight LOCAL_BROWSER_ALLOWED_HOSTS (and LOCAL_BROWSER_ALLOW_ALL=false) before exposing it. Without a token the HTTP path is unauthenticated.

Quick start (tunnel)

# 1. Generate a secret and run in HTTP mode
export LOCAL_BROWSER_TOKEN=$(openssl rand -hex 32)
LOCAL_BROWSER_HTTP_PORT=3000 node dist/server.cjs
#   → [local-browser] HTTP MCP ready on http://127.0.0.1:3000/mcp

# 2. In another shell, expose it over public HTTPS (TLS terminates at the tunnel)
cloudflared tunnel --url http://127.0.0.1:3000     # or: ngrok http 3000
#   → https://something.trycloudflare.com

Then register the connector in claude.ai (also Desktop/Cowork): Customize → Connectors → "+" → name it, enter the public https://…/mcp URL, and put your token in the auth/Bearer field → Add → enable it per-conversation via the "+" in the composer.

Production (always-on)

Host on a box that can run Chromium (VPS, Fly.io, Render, a Playwright-deps container — not serverless edge, which can't spawn Chromium). Set LOCAL_BROWSER_HTTP_HOST=0.0.0.0, keep LOCAL_BROWSER_TOKEN on, and terminate TLS at a reverse proxy (Caddy/nginx) or pass real certs.

GET /health is always open (no secrets) for setup checks; everything else requires the token.

Tools

Tool

Purpose

navigate({ url })

Go to a URL (allowlist-validated)

screenshot({ fullPage?, selector?, format?, quality? })

Image to the agent; format: "jpeg" (+quality 1-100) for lighter captures, else PNG

snapshot()

Flat DOM/a11y snapshot { tag, role, text, ref }

click({ selector | ref })

Click an element

hover({ selector | ref })

Hover (e.g. open a dropdown)

fill({ selector, value })

Fill an input

type({ text })

Type into the focused element

press_key({ key })

Press a key/chord (Enter, Tab, Escape, Control+A, …)

eval({ expression })

Run JS in the page, return JSON result

console() / network()

Buffered console / recent requests

wait_for({ selector?, text?, timeoutMs? })

Wait for a condition

resize({ width, height })

Resize the viewport

reload() / back() / forward()

History nav

get_text()

Visible page text

tabs() / new_tab({ url? }) / switch_tab({ index }) / close_tab({ index? })

Tabs & popups

dialogs() / set_dialog_behavior({ behavior })

JS dialogs (auto-handled; accept/dismiss)

downloads()

Files downloaded this session (saved to LOCAL_BROWSER_DOWNLOAD_DIR)

allow_host / disallow_host / list_allowed

Allowlist management

ref values come from snapshot() (elements are tagged with data-lbmcp-ref), so click({ ref }) targets them reliably.

Security

  • Navigation is rejected unless the host is in LOCAL_BROWSER_ALLOWED_HOSTS (or ALLOW_ALL is on) and the protocol is http/https.

  • The browser uses a fresh, ephemeral profile — no saved cookies, logins, or passwords.

  • eval runs arbitrary JS with the page's full privileges. Harmless on your own dev site; powerful on a real one. With ALLOW_ALL on, every visited page is untrusted input (prompt- injection surface) and the agent can script it — keep ALLOW_ALL off unless you mean it.

  • There's no built-in approval dialog (the server is headless). When run under Claude Code, host additions and eval calls are gated by Claude Code's own per-tool permission prompts.

  • In HTTP mode there is no per-call prompt — the bearer token (LOCAL_BROWSER_TOKEN) is the gate. Set it before exposing the endpoint publicly, and keep the host allowlist tight. See Remote / connector mode.

Develop

npm install        # installs deps + downloads Chromium
npm run typecheck  # tsc --noEmit
npm run build      # bundle → dist/server.cjs
npm test           # spawn the built server, assert the MCP handshake + tool list

Run it by hand over stdio (it waits for JSON-RPC on stdin):

node dist/server.cjs

See CONTRIBUTING.md for the full dev/release workflow.

Project

License

MIT

Available Tools

27 tools
allow_hostA

Add a host (e.g. "github.com") to the navigation allowlist for this session. The client's own per-tool approval is the gate.

Inputs: host (required).

backB

Navigate back in history.

Inputs: no named parameters.

clickB

Click an element by CSS selector or by a ref from snapshot.

Inputs: ref, selector.

close_tabA

Close a tab by index, or the active tab if no index is given. Returns the updated tab list.

Inputs: index.

consoleA

Return buffered console messages (log/warn/error) captured from the page.

Inputs: no named parameters.

dialogsA

Return JS dialogs (alert/confirm/prompt/beforeunload) the page has raised, and how each was handled.

Inputs: no named parameters.

disallow_hostB

Remove a host from the navigation allowlist.

Inputs: host (required).

downloadsA

List files downloaded during this session (url, filename, saved path).

Inputs: no named parameters.

evalA

Evaluate a JavaScript expression in the page context and return the JSON-serializable result. Runs with the page's full privileges — the client's own per-tool approval is the gate.

Inputs: expression (required).

fillC

Fill an input/textarea identified by a CSS selector with the given value.

Inputs: value (required), selector (required).

forwardA

Navigate forward in history.

Inputs: no named parameters.

get_textB

Return the visible text content of the page body.

Inputs: no named parameters.

hoverA

Hover the mouse over an element (by CSS selector or snapshot ref) — e.g. to open a dropdown menu.

Inputs: ref, selector.

list_allowedA

List the hosts the browser may navigate to, and whether all hosts are allowed.

Inputs: no named parameters.

networkA

Return recent network requests (method, url, status, resourceType).

Inputs: no named parameters.

new_tabA

Open a new tab (optionally navigating to a URL) and make it active. Returns the updated tab list.

Inputs: url.

press_keyA

Press a key or chord on the keyboard (e.g. "Enter", "Tab", "Escape", "ArrowDown", "Control+A"). Useful to submit forms or navigate without a mouse.

Inputs: key (required).

reloadB

Reload the current page.

Inputs: no named parameters.

resizeB

Resize the page viewport.

Inputs: width (required), height (required).

screenshotB

Capture a screenshot of the current page (optionally full page or a single element). Use format 'jpeg' (with optional quality 1-100) for a lighter, faster capture; 'png' (default) is lossless.

Inputs: format, quality, fullPage, selector.

set_dialog_behaviorA

Set how JS dialogs are auto-handled: 'accept' (default) or 'dismiss'. beforeunload is always dismissed.

Inputs: behavior (required).

snapshotA

Return a flat accessibility/DOM snapshot (tag, role, text, ref) for element targeting. Use a returned ref with click.

Inputs: no named parameters.

switch_tabB

Switch the active tab by index (see tabs).

Inputs: index (required).

tabsA

List open tabs (index, url, title, and which is active).

Inputs: no named parameters.

typeB

Type text using the keyboard into the currently focused element.

Inputs: text (required).

wait_forC

Wait for a selector to become visible, for text to appear, or for a short delay.

Inputs: text, selector, timeoutMs.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 27 tools

    Disambiguation5/5

    Each tool targets a distinct browser action (navigation, interaction, inspection, tab management, dialogs, downloads, allowlist). No significant overlap; `snapshot` vs `get_text` and `fill` vs `type` are clearly differentiated.

    Naming Consistency5/5

    All tools use lowercase_with_underscores, with action-oriented verbs (e.g., `navigate`, `click`, `wait_for`, `new_tab`). Consistent pattern throughout.

    Tool Count2/5

    With 27 tools, the server exceeds the recommended range. While the breadth is comprehensive, it pushes into the 'too many' territory, risking agent confusion and maintenance overhead.

    Completeness4/5

    The tool set covers core browser operations well, but lacks explicit tools for URL retrieval, scrolling, and cookie management. However, `eval` can work around these gaps, so coverage is mostly complete.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A lightweight 30KB MCP browser automation server that uses raw Chrome DevTools Protocol to enable AI agents to browse the web, take screenshots, interact with elements, and capture live page events like console logs and network requests.
      41
      338 npm
      20
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI clients controlled access to a real headless browser with domain allowlisting, SSRF protection, per-session isolation, audit logging, and persistent cookies/state across restarts.
      11 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A zero-dependency MCP server that drives a real Chrome browser through a companion extension, enabling AI agents to automate real user sessions with trusted input events, compact accessibility-tree snapshots, and 14 tools for navigation, interaction, scripting, and inspection.
      MIT