@bsbofmusic/agent-browser-mcp-opencode

MCP Server for Vercel agent-browser
Browser automation for AI agents via Model Context Protocol

Overview

This package is an MCP (Model Context Protocol) wrapper for agent-browser by Vercel Labs. It provides browser automation capabilities to AI assistants like OpenCode, Claude Code, Cursor, and others through a standardized MCP interface.

✨ Key Features

| Feature | Description | |---------|-------------| | 🚀 One-Click Enable | Auto-installs all dependencies (agent-browser + Chromium) on first run | | 🛠️ Self-Healing | Built-in browser_ensure and browser_doctor tools for auto-repair | | 🔄 Auto-Update | always-latest mode with atomic update support | | 📚 Full Capability Coverage | 15 MCP tools covering all core agent-browser functionality | | ⚡ Universal Passthrough | browser_exec for executing any agent-browser CLI command | | ♻️ Idempotent | Safe to run multiple times, no side effects | | 🪟 Windows Compatibility | Auto-fallback to npx when global install fails | | 📊 Structured Output | All tools return consistent {ok, logs, stdout, stderr, nextSteps} format |

🚀 Quick Start

Option 1: OpenCode Configuration (Recommended)

Add to your opencode.json:

{
  "mcp": {
    "agent-browser-mcp-opencode": {
      "command": ["npx", "-y", "@bsbofmusic/agent-browser-mcp-opencode"],
      "enabled": true,
      "type": "local"
    }
  }
}

Option 2: Direct Run

npx @bsbofmusic/agent-browser-mcp-opencode

Option 3: Global Install

npm install -g @bsbofmusic/agent-browser-mcp-opencode
agent-browser-mcp-opencode

🛠️ MCP Tools

Core Management Tools

| Tool | Description | |------|-------------| | browser_ensure | Manually trigger full repair (install/upgrade agent-browser and Chromium) | | browser_doctor | Diagnose environment issues with actionable nextSteps | | browser_help | List all available commands and capabilities | | browser_version | Show version information for MCP and agent-browser | | browser_exec | Execute any agent-browser CLI command (full passthrough) |

Structured Action Tools

| Tool | Description | |------|-------------| | browser_open | Navigate to a URL | | browser_snapshot | Get accessibility tree with element refs (recommended for AI interaction) | | browser_click | Click an element (@e1 ref or CSS selector) | | browser_fill | Clear and fill a form field | | browser_screenshot | Take a screenshot of the current page | | browser_close | Close the browser and end the session | | browser_get_text | Get text content from an element | | browser_find | Find element by semantic locator (role/text/label/alt etc.) | | browser_wait | Wait for element/text/URL to appear or specified time | | browser_tab | Manage browser tabs (list/create/switch/close) |

💡 Usage Examples

Basic Workflow

// 1. Navigate to page
{"name": "browser_open", "arguments": {"url": "https://example.com"}}

// 2. Get interactive elements with refs
{"name": "browser_snapshot", "arguments": {"interactive": true, "compact": true}}

// 3. Click the first interactive element
{"name": "browser_click", "arguments": {"selector": "@e1"}}

// 4. Fill a form field
{"name": "browser_fill", "arguments": {"selector": "@e2", "value": "[email protected]"}}

// 5. Take a screenshot
{"name": "browser_screenshot", "arguments": {"fullPage": true}}

Semantic Locator

{"name": "browser_find", "arguments": {
  "type": "role",
  "value": "button",
  "action": "click",
  "name": "Submit Form"
}}

Using browser_exec (Advanced)

{"name": "browser_exec", "arguments": {
  "command": "open example.com && snapshot -i && find role button click --name \"Submit\""
}}

⚙️ Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | ALWAYS_LATEST | 1 | Check for agent-browser updates before each call | | UPDATE_STRATEGY | simple | Update strategy: atomic (with rollback) or simple (direct overwrite) | | LOG_LEVEL | info | Log level: error, warn, info, debug | | RUNTIME_DIR | ~/.agent-browser/mcp | Runtime directory for MCP state |

Update Strategies

| Strategy | Description | |----------|-------------| | Simple (default) | Direct overwrite installation, no rollback capability | | Atomic | Uses dual runtime_active/ + runtime_staging/ directories, validates before switching, rolls back on failure |

📁 Runtime Directories

| Directory | Location | Purpose | |-----------|----------|---------| | Config | ~/.agent-browser/ | User configuration and saved sessions | | MCP Runtime | ~/.agent-browser/mcp/ | MCP runtime state and update staging | | Cache | System temp directory | Temporary files and screenshots |

All directories are auto-created on first run and are fully rebuildable.

🔧 Troubleshooting

Run Diagnostics

{"name": "browser_doctor"}

Output includes:

• Issue categories: network/permissions/dependencies/system_libraries/executable/browser/auth
• Severity levels: critical/high/medium
• Actionable nextSteps for fixing issues

Common Issues & Solutions

| Issue | Solution | |-------|----------| | agent-browser not installed | Run browser_ensure or npx agent-browser install | | Chromium not installed | Run npx agent-browser install | | Permission errors | Check npm global directory permissions, or use npx | | Windows daemon issues | Auto-falls back to npx, no manual action needed | | Network issues | Set npm mirror: npm config set registry https://registry.npmmirror.com |

🖥️ Platform Compatibility

| Platform | Status | Notes | |----------|--------|-------| | Windows | ✅ Full | Auto-fallback to npx when PATH issues occur | | macOS | ✅ Full | Native binary works perfectly | | Linux | ✅ Full | Native binary works perfectly |

✅ Verification

6.1 One-Click Deployment

npx @bsbofmusic/agent-browser-mcp-opencode

Expected: Auto-installs all dependencies without manual steps.

6.2 Capability Coverage

All 15 tools are available:

• 5 core management tools
• 10 structured action tools
• Full CLI passthrough via browser_exec

6.3 Stability

• browser_doctor outputs 7 issue categories
• browser_ensure is fully idempotent
• All errors include structured logs and actionable nextSteps

6.4 Auto-Update

• browser_version shows current and latest available versions
• ALWAYS_LATEST=1 checks for updates on every call
• Failed updates do not break existing working environment

6.5 Deployment Ready

No manual configuration required after first enable. Survives MCP and AI agent restarts.

6.6 Failure Scenarios

| Scenario | Expected Output | |----------|-----------------| | No network | Network error + repair steps | | No write permissions | Permission error + npx fallback instructions | | Missing dependencies | Dependency error + install instructions |

📜 Wrapper Declaration

This project is a wrapper for agent-browser by Vercel Labs.

• Upstream Project: https://github.com/vercel-labs/agent-browser
• Upstream License: Apache-2.0
• This is NOT an official upstream release
• Upstream trademarks, names, and copyrights belong to their respective owners
• This package follows all upstream license requirements

See THIRD_PARTY_NOTICES.md for full license details.

📄 License

Apache-2.0 License

Copyright (c) 2024-2025 bsbofmusic

🆘 Support

• MCP Issues: https://github.com/bsbofmusic/agent-browser-mcp-opencode/issues
• Upstream agent-browser Issues: https://github.com/vercel-labs/agent-browser/issues