# Browser Mcp

> Browse MCP for the web, directly from Cursor etc that bridges AI assistants to your local browser through a Chrome extension | MCP helper | MCP assistant | MCP browser

- **Type:** MCP server
- **Install:** `agentstack add mcp-uholli-browser-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [UHolli](https://agentstack.voostack.com/s/uholli)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [UHolli](https://github.com/UHolli)
- **Source:** https://github.com/UHolli/browser-mcp

## Install

```sh
agentstack add mcp-uholli-browser-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Browser MCP Server

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](#overview)
- [Architecture](#architecture)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Development](#development)
- [Testing](#testing)
- [Project Structure](#project-structure)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [FAQ](#faq)
- [License](#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.

```mermaid
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

```mermaid
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

| Module | Role |
|--------|------|
| `src/index.ts` | CLI entry point, tool registration, lifecycle |
| `src/server.ts` | MCP protocol handlers (tools/resources) |
| `src/context.ts` | Typed WebSocket RPC to the extension |
| `src/messaging/` | Request/response correlation over WebSocket |
| `src/tools/` | Browser automation tool implementations |
| `src/persistence/` | Optional Redis session metadata store |
| `src/config/` | Environment-driven configuration |

---

## Features

| Capability | Tools |
|------------|-------|
| **Navigation** | `browser_navigate`, `browser_go_back`, `browser_go_forward`, `browser_wait` |
| **Interaction** | `browser_click`, `browser_hover`, `browser_type`, `browser_select_option`, `browser_drag`, `browser_press_key` |
| **Inspection** | `browser_snapshot`, `browser_screenshot`, `browser_get_console_logs` |
| **Persistence** | Optional Redis-backed session and tool-call metadata |
| **Observability** | Structured stderr logging with configurable log levels |
| **Standalone build** | No private monorepo dependencies required |

---

## Requirements

- **Node.js** 18 or later
- **Chrome** with the [Browser MCP extension](https://browsermcp.io) installed
- **Redis** 6+ (optional, for session persistence)

---

## Installation

### From source

```bash
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):

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

Or use the published binary after linking:

```bash
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:

```bash
cp .env.example .env
```

| Variable | Default | Description |
|----------|---------|-------------|
| `WS_PORT` | `9009` | WebSocket port for the Chrome extension |
| `LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |
| `REDIS_ENABLED` | `false` | Enable Redis session persistence |
| `REDIS_HOST` | `127.0.0.1` | Redis hostname |
| `REDIS_PORT` | `6379` | Redis port |
| `REDIS_PASSWORD` | _(empty)_ | Redis authentication password |
| `REDIS_DB` | `0` | Redis database index |
| `REDIS_KEY_PREFIX` | `browsermcp:` | Key namespace prefix |
| `REDIS_CONNECT_TIMEOUT_MS` | `10000` | Connection timeout |
| `REDIS_MAX_RETRIES` | `10` | Reconnection attempts |
| `REDIS_SESSION_TTL_SECONDS` | `86400` | Session key TTL (24 h) |

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

---

## Development

```bash
# 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:

```bash
npm run build
npm run inspector
```

---

## Testing

```bash
# 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:

```bash
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:

```bash
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](LICENSE).

Adapted from the [Playwright MCP server](https://github.com/microsoft/playwright-mcp) with a browser-extension architecture for profile reuse and stealth automation.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [UHolli](https://github.com/UHolli)
- **Source:** [UHolli/browser-mcp](https://github.com/UHolli/browser-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-uholli-browser-mcp
- Seller: https://agentstack.voostack.com/s/uholli
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.