MCP Browser Runtime

A local, Node.js Model Context Protocol server for browser inspection and explicitly approved interaction, built with Playwright. It combines configurable capture profiles, bounded responses, multi-page/frame state, and operator-controlled capabilities.

Status: experimental developer tool. Suitable for evaluation with synthetic data, not production accounts or untrusted multi-tenant workloads. Independent project; not Microsoft's official Playwright MCP implementation.

Why this project exists

Browser agents need useful page context without unrestricted browser or filesystem access. This runtime explores that trade-off through explicit network policy, response budgets, temporary sessions, and confirmation before supported mutations.

• Context control: light, balanced, and full capture profiles, with bounded structured responses and viewport JPEG screenshots.

• Browser state: stable page identifiers, frame-aware inspection, DOM and accessibility helpers, and an owned browser lifecycle.

• Network policy: exact allowed origins and private-address checks backed by a per-browser proxy that connects to the IP it validated.

• Approval: interaction is disabled by default; enabling it still requires per-action MCP form elicitation through the client.

• Local boundaries: temporary Chromium contexts, explicit file roots, exclusive new-file writes, and metadata-only observability.

• Engineering evidence: real stdio protocol tests, synthetic browser fixtures, generated tool documentation, package-content checks, and cross-platform CI.

There are 35 tools enabled by the default configuration. The generated reference lists all 71 retained descriptors and their availability. Disabled legacy entries are not advertised as working features. No comparative speed, accuracy, or token-saving benchmark is claimed.

Related MCP server: Browser MCP

Quickstart

Prerequisites: Git, Node.js 22.13 or later, and npm. CI targets Node 22 and 24 on Windows and Ubuntu; macOS and individual MCP client versions are not certified.

git clone https://github.com/Mhrnqaruni/mcp-browser-runtime.git
cd mcp-browser-runtime
npm ci --ignore-scripts
npm run doctor
node node_modules/playwright/cli.js install chromium

On Linux, browser system dependencies may also be needed: node node_modules/playwright/cli.js install --with-deps chromium. Installation downloads packages/browser binaries; no account or API key is needed.

doctor starts the real MCP server, initializes the protocol, lists tools, and calls a capture-profile tool. It does not launch a browser or call an AI model. Successful output includes "status": "ok" and "liveModelCalls": 0.

Connect a client

Configure your MCP client to launch node directly with the absolute path to src/mcp-browser-server.js. For clients using an mcpServers configuration shape:

{
  "mcpServers": {
    "browser-runtime": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-browser-runtime/src/mcp-browser-server.js"],
      "env": {
        "MCP_ALLOWED_ORIGINS": "[\"https://example.com\"]",
        "MCP_ENABLE_MUTATIONS": "false"
      }
    }
  }
}

Replace the path; on Windows, use a valid absolute path with forward slashes or JSON-escaped backslashes. Client configuration formats vary: adapt this example to your client's documentation. Do not use npm start as the stdio command: its banner is not MCP protocol traffic.

The inspection sequence is browser.launch → browser.goto → browser.snapshot or browser.screenshot → browser.close. With no configured origins, network destinations are denied. Cross-origin assets need their own explicit origin entries; there is no wildcard mode.

Try the owned demo

npm run demo:site

This starts a synthetic site at http://127.0.0.1:8000. Configure MCP_LOCAL_TEST_ORIGINS=["http://127.0.0.1:8000"] in the server environment. The exception applies only to that literal address and port. See demo instructions for the form, frame, dialog and tab workflow. No real account, personal browser profile or external-site submission is required.

Capabilities and limits

Clients without MCP form elicitation cannot authorize interaction. Do not work around this with automatic approval. Cookie values, storage state, local files, page content and screenshots can be sensitive even when access is authorized.

Read configuration, tool schemas, security model, and privacy before enabling capabilities.

Architecture

MCP client
  └─ stdio entrypoint
       └─ tool policy → confirmation → serialized dispatch → response budget
            ├─ managed Chromium → validating proxy → allowed origins
            ├─ file tools → explicit read/write roots
            └─ optional PDF worker → bounded child process

src/tools/ separates definitions into eleven domains. src/server/ composes shared state and registration; src/browser/ owns browser helpers and lifecycle; src/security/ contains capability, file, navigation, proxy and parser controls. There is one stateful session per process, not a multi-tenant server. See architecture for the boundaries and remaining refactoring.

Development and verification

npm run lint
npm run format:check
npm test
npm run docs:check
npm run pack:check
npm run pack:verify
npm audit --omit=dev

Tests use synthetic local fixtures and actual MCP stdio traffic. The browser workflow checks navigation denial, approval, screenshots, session restore and owned shutdown. Legacy tests are retained separately; only those documented in testing are claimed as exercised. The CI badge links to actual results; its presence is not a claim that every run passes.

npm run docs:generate refreshes the tool reference. pack:verify installs the allowlisted artifact outside the checkout and runs its doctor. npm publication is deliberately blocked with private: true; install from source.

Security and project status

This public successor starts with clean Git history and excludes old personal artifacts, profiles and runtime data. Historical personal material remains in the predecessor's history; this repository does not erase earlier copies or caches.

Publication does not finish runtime hardening. Known limitations include PDF cold-start/deadline reliability, residual filesystem/action races, unsupported legacy capabilities, and incomplete adversarial coverage. See the explicit readiness checklist, not just the README, before relying on it.

The runtime is not an OS security boundary. A malicious client can fake approval; a page can change after confirmation; same-user processes can race files. V8 heap limits do not bound all native memory. Use an isolated environment and synthetic data; do not attach production or customer accounts. No exhaustive security audit or production support commitment is claimed.

Contributing and license

Use a topic branch and a reviewed pull request; do not commit directly to main. See contribution guidance, changelog, and security reporting. Never put secrets or private browser state in issues or CI artifacts.

The inherited ISC license is retained, including its original notice. It permits commercial use. This publication does not introduce a noncommercial license or change third-party dependency terms.