Local Browser MCP
This server provides an MCP-controllable real browser (Playwright) that an agent can drive to interact with local web apps and allowed hosts.
Navigate to URLs (validated against an allowlist or all hosts if enabled)
Take screenshots (full page, element, PNG/JPEG with quality)
Get a DOM/accessibility snapshot with stable refs for element targeting
Click, hover, fill inputs, type text, and press keys/chords
Run arbitrary JavaScript in the page via
evalRead buffered console messages and recent network requests
Wait for selectors, text, or a timeout
Resize the viewport and reload/back/forward navigation
Get visible page text
Manage tabs and popups: list, open, switch, close tabs
Handle JavaScript dialogs (accept/dismiss) and inspect dialog history
List downloaded files from the session
Manage the navigation allowlist: list hosts, request host additions, remove hosts
Provides the ability to use Firefox as the browser engine, enabling automated control of Firefox for navigation, clicking, screenshots, DOM snapshotting, and other browser automation tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Local Browser MCP navigate to http://localhost:3000 and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local Browser MCP
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.
Claude Code / any MCP client (recommended)
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-marketplaceThe plugin's MCP server is the same npx invocation above.
Related MCP server: Secure Browser MCP
Configuration (environment variables)
Variable | Default | Purpose |
|
|
|
|
| Comma-separated navigation allowlist |
|
|
|
| — |
|
| — | If set, run in HTTP mode on this port (else stdio) |
|
| HTTP bind address; use |
| — | If set, HTTP requests need |
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 setLOCAL_BROWSER_TOKENand keep a tightLOCAL_BROWSER_ALLOWED_HOSTS(andLOCAL_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.comThen 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 |
| Go to a URL (allowlist-validated) |
| Image to the agent; |
| Flat DOM/a11y snapshot |
| Click an element |
| Hover (e.g. open a dropdown) |
| Fill an input |
| Type into the focused element |
| Press a key/chord (Enter, Tab, Escape, Control+A, …) |
| Run JS in the page, return JSON result |
| Buffered console / recent requests |
| Wait for a condition |
| Resize the viewport |
| History nav |
| Visible page text |
| Tabs & popups |
| JS dialogs (auto-handled; accept/dismiss) |
| Files downloaded this session (saved to |
| 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(orALLOW_ALLis on) and the protocol is http/https.The browser uses a fresh, ephemeral profile — no saved cookies, logins, or passwords.
evalruns arbitrary JS with the page's full privileges. Harmless on your own dev site; powerful on a real one. WithALLOW_ALLon, every visited page is untrusted input (prompt- injection surface) and the agent can script it — keepALLOW_ALLoff 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 listRun it by hand over stdio (it waits for JSON-RPC on stdin):
node dist/server.cjsSee CONTRIBUTING.md for the full dev/release workflow.
Project
License
Available Tools
27 toolsallow_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
Scored across 27 tools
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.
All tools use lowercase_with_underscores, with action-oriented verbs (e.g., `navigate`, `click`, `wait_for`, `new_tab`). Consistent pattern throughout.
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.
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
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Related MCP Servers
- AlicenseAqualityBmaintenanceA 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.41338 npm20MIT
- AlicenseNot gradedqualityDmaintenanceAn 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 npmMIT
- AlicenseNot gradedqualityBmaintenanceA 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
- FlicenseAqualityCmaintenanceAn MCP server that gives AI agents mouse-and-keyboard control over a live Chrome session, enabling navigation, clicking, typing, screenshots, and DOM inspection.13-