Browser MCP Server

A production-ready Model Context Protocol (MCP) server that bridges AI assistants to your local browser through a Chrome extension.

Control navigation, interaction, snapshots, and screenshots from Cursor, Claude Desktop, VS Code, Windsurf, and any MCP-compatible client — without launching a separate browser instance.

Table of Contents

• Overview
• Architecture
• Features
• Requirements
• Installation
• Configuration
• Development
• Testing
• Project Structure
• Troubleshooting
• Contributing
• FAQ
• License

Overview

Browser MCP connects an AI client (via stdio MCP transport) to a Chrome extension (via local WebSocket). The extension operates on your existing browser profile, preserving login sessions and reducing bot-detection friction compared to headless automation.

flowchart TB
    subgraph Client["AI Client"]
        MCP["MCP Host\n(Cursor / Claude / VS Code)"]
    end

    subgraph Server["MCP Server (this repo)"]
        STDIO["Stdio Transport"]
        CORE["Tool Handler"]
        WS["WebSocket Bridge :9009"]
        REDIS[("Redis\n(optional)")]
    end

    subgraph Browser["User Browser"]
        EXT["Chrome Extension"]
        TAB["Active Tab"]
    end

    MCP <-->|JSON-RPC stdio| STDIO
    STDIO --> CORE
    CORE --> WS
    CORE -.->|session metadata| REDIS
    WS <-->|typed messages| EXT
    EXT --> TAB

Architecture

Request Flow

sequenceDiagram
    participant AI as AI Client
    participant MCP as MCP Server
    participant WS as WebSocket
    participant EXT as Chrome Extension
    participant Page as Browser Tab

    AI->>MCP: tools/call browser_navigate
    MCP->>WS: browser_navigate { url }
    WS->>EXT: JSON message + requestId
    EXT->>Page: navigate
    Page-->>EXT: loaded
    EXT-->>WS: messageResponse { result }
    WS-->>MCP: success
    MCP->>WS: browser_snapshot
    WS->>EXT: snapshot request
    EXT-->>MCP: ARIA tree YAML
    MCP-->>AI: text content + snapshot

Component Responsibilities

Features

Requirements

• Node.js 18 or later
• Chrome with the Browser MCP extension installed
• Redis 6+ (optional, for session persistence)

Installation

From source

git clone https://github.com/BrowserMCP/mcp.git
cd mcp
npm install
npm run build

MCP client configuration

Add to your MCP client settings (example for Cursor / Claude Desktop):

{
  "mcpServers": {
    "browsermcp": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"]
    }
  }
}

Or use the published binary after linking:

npm link
# command: mcp-server-browsermcp

Connect the extension

1. Start your MCP client (which launches this server).
2. Open Chrome and click the Browser MCP extension icon.
3. Click Connect on the active tab.
4. Invoke tools from your AI assistant.

Configuration

Copy the example environment file and adjust values:

cp .env.example .env

When Redis is enabled, the server records connection events, disconnection timestamps, and tool-call counts — useful for debugging and operational monitoring.

Development

# Install dependencies
npm install

# Watch mode
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

# Run all checks
npm run validate

MCP Inspector

Debug tool schemas and handlers interactively:

npm run build
npm run inspector

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

Tests cover environment parsing, error formatting, async utilities, and Redis session store logic (with mocked clients).

Project Structure

mcp/
├── docs/
│   └── AUDIT.md              # Engineering audit notes
├── src/
│   ├── config/               # App + environment configuration
│   ├── messaging/            # WebSocket RPC layer
│   ├── persistence/          # Redis connection + session store
│   ├── resources/            # MCP resource type definitions
│   ├── tools/                # Browser automation tools
│   ├── types/                # Shared Zod schemas and message types
│   ├── utils/                # Logging, errors, port helpers
│   ├── context.ts            # Extension connection context
│   ├── index.ts                # CLI entry point
│   ├── server.ts             # MCP server factory
│   └── ws.ts                 # WebSocket server lifecycle
├── tests/                    # Vitest unit tests
├── .env.example              # Configuration template
├── eslint.config.js          # ESLint flat config
├── tsup.config.ts            # Build configuration
├── tsconfig.json             # TypeScript (source)
├── tsconfig.test.json        # TypeScript (tests + lint)
└── vitest.config.ts          # Test runner config

Design Decisions

• Stdio transport only — MCP clients spawn the server as a subprocess; stdout is reserved for the protocol.
• Stderr logging — All diagnostics go to stderr to avoid corrupting MCP messages.
• Optional Redis — Persistence is opt-in; the server runs fully without Redis for local development.
• Typed WebSocket RPC — Every extension message is typed end-to-end for compile-time safety.

Troubleshooting

"No connection to browser extension"

The Chrome extension is not connected. Open the extension popup and click Connect on the target tab.

Port already in use

Another process holds WS_PORT (default 9009). Either stop the conflicting process or set a different port:

WS_PORT=9010 node dist/index.js

Redis connection failures

If Redis is enabled but unreachable, the server logs an error and continues without persistence. Verify Redis is running:

redis-cli ping
# PONG

Tools return timeout errors

The extension did not respond within 30 seconds. Ensure the tab is active and the extension is connected. Increase load times with browser_wait.

MCP client shows no tools

Confirm the server binary path in your MCP config is absolute and that npm run build completed successfully.

Contributing

1. Fork the repository and create a feature branch.
2. Install dependencies: npm install
3. Make changes with tests: npm run validate
4. Submit a pull request with a clear description and test plan.

Commit Guidelines

• One logical change per commit.
• Use conventional prefixes: feat:, fix:, refactor:, test:, docs:, chore:.
• Run npm run validate before pushing.

FAQ

Does this launch a new browser?
No. It controls your existing Chrome profile through an extension.

Is my data sent to remote servers?
Automation runs locally. Data only flows between your AI client, this server, and your browser.

Do I need Redis?
No. Redis is optional and disabled by default.

Which browsers are supported?
Chrome and Chromium-based browsers with the Browser MCP extension.

How is this different from Playwright MCP?
Playwright MCP launches browser instances. Browser MCP uses your logged-in profile via a Chrome extension, reducing CAPTCHA and login friction.

Can multiple extensions connect?
Only one WebSocket connection is active at a time. A new connection replaces the previous one.

License

Apache License 2.0 — see LICENSE.

Adapted from the Playwright MCP server with a browser-extension architecture for profile reuse and stealth automation.