Browser Agents MCP

Upgraded version of 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)

Related MCP server: UBA MCP Server

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

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

2. Install dependencies

npm install

3. Install Chromium for Playwright

npx playwright install chromium

4. Create the environment file

Create a file named .env in the project root:

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

Leave CAPTCHA_API_KEY empty to disable CAPTCHA solving.

5. Build

npm run build

6. Start the server

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:

{
  "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

ngrok http 3000

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

Option 2: Cloudflare Tunnel (free, temporary)

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:

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

Inspection

Interaction

Forms and Files

Tabs

Waiting

Reading

Sessions and Permissions

CAPTCHA

Identity and Accounts

Agent Messaging

High-Level

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:

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.