# @nxavis/agent-browser-mcp

[![npm version](https://img.shields.io/npm/v/@nxavis/agent-browser-mcp.svg)](https://www.npmjs.com/package/@nxavis/agent-browser-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides browser automation capabilities through [Vercel's agent-browser](https://github.com/vercel-labs/agent-browser). This enables LLMs to interact with web pages using a fast Rust CLI with Node.js fallback.

## Quick Start

```bash
# 1. Install agent-browser CLI
npm install -g agent-browser && agent-browser install

# 2. Add to Claude Desktop (or your MCP client)
npx @nxavis/agent-browser-mcp
```

Then use tools like `browser_navigate`, `browser_click`, `browser_snapshot` to control the browser from your AI agent.

## Features

- **AI-Optimized Browser Control** - Semantic element locators using accessibility properties, text matching, and data attributes
- **Session Isolation** - Multiple isolated browser sessions with separate cookies, storage, and navigation history
- **Comprehensive Automation** - Navigation, form filling, clicking, scrolling, keyboard input, and more
- **Data Extraction** - Get text, HTML, attributes, accessibility snapshots, screenshots, and PDFs
- **Cookie Management** - Full control over browser cookies and storage
- **JavaScript Execution** - Run arbitrary scripts in the browser context
- **Network Inspection** - Monitor console messages and network requests

## Installation

```bash
npm install @nxavis/agent-browser-mcp
```

Or run directly with npx:

```bash
npx @nxavis/agent-browser-mcp
```

### Prerequisites

- Node.js 18 or newer
- [agent-browser](https://github.com/vercel-labs/agent-browser) CLI installed:

```bash
# Install agent-browser globally
npm install -g agent-browser

# Download Chromium browser
agent-browser install

# On Linux, install system dependencies if needed:
# agent-browser install --with-deps
```

> **⚠️ Windows Note:** agent-browser currently has [known issues on Windows](https://github.com/vercel-labs/agent-browser/issues/56) with native shells (PowerShell/CMD). For Windows users, we recommend using [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install) until the upstream issue is resolved.

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["@nxavis/agent-browser-mcp"]
    }
  }
}
```

### VS Code

Add to your VS Code settings (JSON):

```json
{
  "mcp": {
    "servers": {
      "agent-browser": {
        "command": "npx",
        "args": ["@nxavis/agent-browser-mcp"]
      }
    }
  }
}
```

### Antigravity

Add to your `.mcp.json` file in your project root or home directory:

```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["@nxavis/agent-browser-mcp"]
    }
  }
}
```

Or use the global configuration at `~/.mcp.json`:

```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["@nxavis/agent-browser-mcp"],
      "env": {
        "AGENT_BROWSER_PATH": "/usr/local/bin/agent-browser"
      }
    }
  }
}
```

### Custom agent-browser Path

If `agent-browser` is not in your PATH, specify its location:

```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["@nxavis/agent-browser-mcp"],
      "env": {
        "AGENT_BROWSER_PATH": "/path/to/agent-browser"
      }
    }
  }
}
```

## Available Tools

### Navigation

- `browser_navigate` - Navigate to a URL
- `browser_go_back` - Navigate back in browser history
- `browser_go_forward` - Navigate forward in browser history
- `browser_reload` - Reload the current page

### Interaction

- `browser_click` - Click on an element
- `browser_fill` - Fill a text input field
- `browser_type` - Type text character by character
- `browser_hover` - Hover over an element
- `browser_scroll` - Scroll the page or a specific element
- `browser_select` - Select an option from a dropdown
- `browser_check` - Check a checkbox or radio button
- `browser_uncheck` - Uncheck a checkbox
- `browser_press` - Press a keyboard key

### Data Extraction

- `browser_get_text` - Get text content from an element or page
- `browser_get_html` - Get HTML content
- `browser_get_attribute` - Get an attribute value
- `browser_get_url` - Get the current page URL
- `browser_get_title` - Get the current page title
- `browser_snapshot` - Get accessibility tree snapshot

### Session Management

- `browser_new_session` - Create a new isolated browser session
- `browser_close_session` - Close a browser session

### Screenshots & PDF

- `browser_screenshot` - Take a screenshot
- `browser_pdf` - Generate a PDF of the current page

For a complete list of tools and their parameters, see the [original documentation](https://github.com/vercel-labs/agent-browser).

## Development

```bash
# Clone the repository
git clone https://github.com/nxavis/agent-browser-mcp.git
cd agent-browser-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev
```

## License

MIT

## Credits

This package is based on [agent-browser-mcp](https://github.com/minhlucvan/agent-browser-mcp) by minhlucvan, adapted for the @nxavis ecosystem.