# Browser Agents MCP
**Upgraded version of [web-agent-mcp](https://github.com/sankalpsinghcoder-ai/web-agent-mcp)**

**Note: 70% of the README is generated by AI and checked before committing**

---

An MCP (Model Context Protocol) server that gives AI assistants full control of a real web browser. It exposes 42 tools for navigation, clicking, typing, form filling, file uploads, downloads, CAPTCHA solving, identity management, and multi-agent coordination. Each AI agent gets its own isolated browser session with a persistent profile and its own stored identity.

---

## Features

- 42 browser automation tools exposed over MCP
- Multi-agent support with isolated sessions per `agentId`
- Persistent browser profiles (cookies, logins survive restarts)
- Human-like mouse movement, typing, and scrolling
- Stealth mode to reduce bot detection
- Automatic CAPTCHA detection and solving (reCAPTCHA v2, hCaptcha, Turnstile, image CAPTCHAs via 2Captcha)
- Built-in identity vault with temporary email inboxes for signup and signin flows
- In-memory agent-to-agent messaging
- High-level `browser_task` tool to run a sequence of actions in one call
- Streamable HTTP transport (MCP compatible)

---

## Requirements

- Node.js 18 or higher
- Git
- Chromium (installed automatically by Playwright)
- Optional: a 2Captcha API key for CAPTCHA solving

---

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/sankalpsinghcoder-ai/browser-agents-mcp.git
cd browser-agents-mcp
```

### 2. Install dependencies

```bash
npm install
```

### 3. Install Chromium for Playwright

```bash
npx playwright install chromium
```

### 4. Create the environment file

Create a file named `.env` in the project root:

```env
PORT=3000
CAPTCHA_API_KEY=
PROFILES_DIR=./profiles
VAULT_DIR=./vault
```

Leave `CAPTCHA_API_KEY` empty to disable CAPTCHA solving.

### 5. Build

```bash
npm run build
```

### 6. Start the server

```bash
npm start
```

You should see:

```
Web Agent MCP v0.3.0 running on port 3000
MCP endpoint: http://localhost:3000/mcp
CAPTCHA solving: disabled
```

---

## Verifying the Server

Open a browser and visit:

```
http://localhost:3000/health
```

Expected response:

```json
{
  "status": "ok",
  "service": "web-agent-mcp",
  "version": "0.3.0",
  "sessions": [],
  "captchaEnabled": false
}
```

---

## Remote Access

`localhost` only works if the AI client runs on the same machine as the server. To expose the server to a remote client, use one of these options.

### Option 1: ngrok

```bash
ngrok http 3000
```

Use the provided HTTPS URL plus `/mcp` as your endpoint.

### Option 2: Cloudflare Tunnel (free, temporary)

```bash
cloudflared tunnel --url http://localhost:3000
```

Use the provided HTTPS URL plus `/mcp`.

### Option 3: Deploy to a VPS (permanent)

On the server, set `headless: true` inside `index.ts`, rebuild, then run with a process manager:

```bash
npm install -g pm2
pm2 start dist/index.js --name browser-agents
pm2 save
pm2 startup
```

Place Nginx or Caddy in front for HTTPS.

**Warning:** this server has no authentication. Never expose it publicly without adding an auth layer (reverse proxy with API key, Cloudflare Access, or a private network such as Tailscale).

---

## Tool Reference

### Navigation

| Tool | Description |
|------|-------------|
| `browser_navigate` | Open a URL in the active tab |
| `browser_back` | Go back in history |
| `browser_forward` | Go forward in history |
| `browser_reload` | Reload the page |

### Inspection

| Tool | Description |
|------|-------------|
| `browser_inspect` | List interactive elements and visible text |
| `browser_inspect_semantic` | Semantic inspection with roles and labels |
| `browser_get_element` | Find an element by css, text, role, label, or placeholder |
| `browser_extract` | Extract structured data matching a selector |

### Interaction

| Tool | Description |
|------|-------------|
| `browser_click` | Human-like click on element at index |
| `browser_type` | Human-like typing into an input |
| `browser_select` | Select an option from a dropdown |
| `browser_hover` | Move mouse over an element |
| `browser_keyboard` | Press a key or type text |
| `browser_scroll` | Human-like scroll |

### Forms and Files

| Tool | Description |
|------|-------------|
| `browser_fill_form` | Fill multiple fields in one call |
| `browser_upload_file` | Upload files to a file input |
| `browser_download` | Click a download link and save the file |

### Tabs

| Tool | Description |
|------|-------------|
| `browser_new_tab` | Open a new tab |
| `browser_switch_tab` | Switch to a tab |
| `browser_close_tab` | Close a tab |
| `browser_list_tabs` | List all open tabs |

### Waiting

| Tool | Description |
|------|-------------|
| `browser_wait` | Sleep for a number of milliseconds |
| `browser_wait_for_element` | Wait for an element to reach a state |
| `browser_wait_for_text` | Wait for text to appear |
| `browser_wait_for_navigation` | Wait for navigation to complete |

### Reading

| Tool | Description |
|------|-------------|
| `browser_read` | Read visible page text |
| `browser_screenshot` | Capture a PNG screenshot |

### Sessions and Permissions

| Tool | Description |
|------|-------------|
| `browser_session` | Inspect, close, or clear a session |
| `browser_list_sessions` | List all active agent sessions |
| `browser_permissions` | Grant or clear browser permissions |
| `browser_profile` | Show the persistent profile path |

### CAPTCHA

| Tool | Description |
|------|-------------|
| `captcha_detect` | Detect the CAPTCHA type on the page |
| `captcha_solve` | Solve any CAPTCHA on the page |
| `browser_click_and_solve` | Click an element, then solve any CAPTCHA that appears |

### Identity and Accounts

| Tool | Description |
|------|-------------|
| `identity_get` | Get the agent's stored email and password |
| `identity_create_inbox` | Create a temporary email inbox |
| `identity_wait_email` | Wait for an email to arrive |
| `account_signup` | Sign up using the agent's identity |
| `account_signin` | Sign in using the agent's identity |

### Agent Messaging

| Tool | Description |
|------|-------------|
| `agent_send` | Send a message to another agent |
| `agent_receive` | Read messages for this agent |

### High-Level

| Tool | Description |
|------|-------------|
| `browser_task` | Execute a sequence of actions in one call |

---

## Project Structure

```
browser-agents-mcp/
  dist/              compiled JavaScript (gitignored)
  node_modules/      dependencies (gitignored)
  profiles/          per-agent browser profiles (gitignored)
  vault/             per-agent identity files (gitignored)
  src/               optional source folder
  index.ts           main source file
  .env               environment variables (gitignored)
  .env.example       environment template
  .gitignore
  package.json
  package-lock.json
  tsconfig.json
```

---

## Configuration

Environment variables read at startup:

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3000` | HTTP server port |
| `CAPTCHA_API_KEY` | empty | 2Captcha API key. Empty disables CAPTCHA solving. |
| `PROFILES_DIR` | `./profiles` | Folder for persistent browser profiles |
| `VAULT_DIR` | `./vault` | Folder for stored agent identities |

---

## Security Notes

- The server has no authentication. Do not expose it publicly without protection.
- `profiles/` contains live browser sessions (cookies, tokens). Never commit or share it.
- `vault/` contains agent emails and passwords. Never commit or share it.
- `.env` contains API keys. Never commit it.
- Use Tailscale, Cloudflare Access, or a reverse proxy with an API key if you need remote access.

---

## Disclaimer

This project is intended for research and automation. Users are responsible for how they use it. Do not use it to violate website terms of service or applicable laws.