ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use Browser Use MCP with OpenCode

Connect Browser Use to OpenCode with the current MCP configuration, verify the server, run a browser task, and troubleshoot local or cloud setups.

By the ScreenshotNeo team1 October 20268 min read

Use Browser Use’s local MCP server as an OpenCode local server. The documented command is uvx --from 'browser-use[cli]' browser-use --mcp. In current OpenCode v2, put that command in a named object under mcp.servers, run opencode mcp list, then ask OpenCode to perform a small browser task.

Browser Use here means the browser-use project. Several unrelated products use similar names, so check that your package and command match the project documentation.

1. Check your OpenCode configuration format

OpenCode v2 documents MCP servers under mcp.servers. Each local server has type: "local" and a command array. Earlier OpenCode documentation used a different, flatter shape. Use the schema documented for the version installed on your machine; do not combine fields from both formats.

The current v2 documentation is the authority for the configuration shape and status command: OpenCode MCP servers documentation.

2. Install the local Browser Use runner

Browser Use documents this local stdio command:

uvx --from 'browser-use[cli]' browser-use --mcp

uvx runs a Python package command without requiring you to maintain a project virtual environment. Make sure the uvx executable is installed and available on the PATH seen by OpenCode. The Browser Use repository also publishes a server manifest with its package and runtime hints; package versions and installation instructions can change, so check the current repository before pinning anything.

3. Add Browser Use to OpenCode

For OpenCode v2, add a named server to your OpenCode configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "browser-use": {
        "type": "local",
        "command": [
          "uvx",
          "--from",
          "browser-use[cli]",
          "browser-use",
          "--mcp"
        ]
      }
    }
  }
}

This combines Browser Use’s documented launch command with OpenCode v2’s documented local-server schema. If your installed OpenCode release uses the older layout, follow that release’s own MCP documentation instead of copying this nesting.

Keep the command as an array

Each executable argument is a separate array item. This avoids shell quoting differences and lets OpenCode start the process directly over stdio.

4. Confirm that OpenCode can connect

Run the documented status command from a terminal:

opencode mcp list

Find browser-use in the output and confirm that it is connected. If it is unavailable or disconnected, work through the troubleshooting checklist below before attempting a complex task.

  • uvx --from 'browser-use[cli]' browser-use --mcp starts successfully when run directly.
  • The OpenCode process can find uvx on its PATH.
  • The configuration file is the one used by your OpenCode installation.
  • The server name and JSON nesting match your installed OpenCode version.
  • You used --mcp, not --cli-mcp, unless the Browser Use version explicitly requires that interface.

5. Run a small browser task first

Start with a public page and a read-only request. For example, ask OpenCode:

Use Browser Use to open https://example.com and tell me the page title and the first visible paragraph. Do not submit forms or change anything.

This verifies that OpenCode can see the connected Browser Use tools and that the browser can navigate and read a page. Browser Use documents browser automation tasks and MCP tools in its integration guide; treat this as a verification task to run in your environment, not as a guaranteed result.

Move from reading to interaction

Once the read-only check works, describe one action at a time and state the stopping condition:

Open https://example.com, find the link named “More information,” click it, and report the destination page title. Do not enter data or download files.

For sites that require authentication, provide credentials through the mechanism supported by your environment rather than placing secrets in prompts or configuration committed to source control.

6. Choose local or cloud Browser Use MCP

Browser Use documents two integration paths. The local path starts a process on your machine and communicates over stdio. The cloud path uses a hosted endpoint and an API-key header.

Question Local MCP Cloud MCP
Where does the browser run? Through the local Browser Use command configured in OpenCode. Through Browser Use’s hosted MCP endpoint.
OpenCode transport Local process over stdio. Remote MCP endpoint.
Endpoint None; OpenCode launches the command. https://api.browser-use.com/mcp
Authentication Local runtime and any credentials your task requires. x-browser-use-api-key header, as shown in Browser Use’s integration guide.
Best fit You want the browser process and profile close to your development environment. You want hosted browser task execution or the cloud tool surface.
Pricing and terms Not established by the cited setup documents. Verify current account requirements, pricing, data handling, and terms before adopting it.

Browser Use’s integration guide lists cloud tools such as browser_task, execute_skill, and task monitoring. Read the current Browser Use integrations guide before configuring the hosted route.

Cloud configuration considerations

The exact remote-server configuration depends on the OpenCode release and its current remote MCP schema. Use the OpenCode documentation for that release, set the endpoint to the documented Browser Use URL, and supply the API key through the required header. Do not assume that local command fields apply to a remote server.

7. Troubleshooting

“Command not found: uvx”

Cause: uvx is not installed or is not on the PATH inherited by OpenCode.

Fix: Run command -v uvx in the same account and shell context used to start OpenCode. Install or expose the required Python/uv tooling, then restart OpenCode. A command that works in one terminal may still be invisible to a GUI-launched process with a different environment.

The server appears disconnected

Cause: OpenCode may be reading a different configuration file, or the JSON shape may belong to another OpenCode version.

Fix: Validate the file location, confirm the mcp.servers nesting for OpenCode v2, and run opencode mcp list again. Check the current OpenCode MCP documentation rather than mixing examples from older guides.

The process starts and exits immediately

Cause: The package command, optional CLI dependency, or Browser Use flag may have changed.

Fix: Run the documented command directly:

uvx --from 'browser-use[cli]' browser-use --mcp

Then compare the installed Browser Use release with its current repository instructions. Browser Use’s CLI distinguishes --mcp from --cli-mcp; do not substitute one for the other without confirming the intended tool surface.

OpenCode connects but no Browser Use tools appear

Cause: The process may be running a different entry point, or OpenCode may need to be restarted after configuration changes.

Fix: Confirm the server name, restart OpenCode, and inspect opencode mcp list. Verify that the command is the Browser Use MCP entry point and that the package includes its CLI extras.

A browser task fails on a particular website

Cause: The page may require login, block automation, depend on a region, or load content only after additional interaction.

Fix: Reduce the task to one navigation or extraction step, use a public page to isolate the connection, and describe the required state explicitly. Treat authentication, consent dialogs, downloads, and destructive actions as separate steps that need deliberate handling.

Cloud authentication fails

Cause: The API key header, endpoint, account, or current cloud requirements may be wrong or outdated.

Fix: Check the current Browser Use integration guide for the exact x-browser-use-api-key header and endpoint. Confirm the key is available to the OpenCode process without exposing it in logs or committed files. Verify current service terms and account status.

8. Performance, reliability, and cost notes

  • Start with small tasks: A title or paragraph extraction makes connection failures easy to distinguish from website-specific failures.
  • Keep prompts deterministic: Name the URL, the target element or text, the allowed actions, and the expected stopping condition.
  • Separate retries from actions: If a page is slow, retry navigation or inspection before repeating a click or form submission.
  • Watch environment differences: Local runs depend on the OpenCode process environment, installed uv/Python tooling, browser availability, and network access.
  • Pin deliberately: Browser Use’s documented command is unpinned. If reproducibility matters, choose and maintain a package version after checking the current release instructions.
  • Do not invent cost comparisons: The cited setup documents establish the local command and cloud endpoint but do not provide a complete current price comparison. Check the provider’s current terms before selecting a route.

9. Or skip the browser setup

If your goal is a clean screenshot rather than interactive browser control, ScreenshotNeo provides a single HTTP request for a PNG, JPEG, WebP, or PDF. Its capture pipeline accepts cookie and consent banners, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets you turn each step off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; the response identifies the result with X-Page-Verdict and X-Billed headers.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', data));

ScreenshotNeo also supports full-page capture with lazy images loaded, CSS-selector element shots, dark mode, device presets and custom viewports, retina scale, PDF paper settings and page ranges, custom CSS and JavaScript, clicks, selector or network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, usage reporting, and an OpenAPI specification.

An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

10. FAQ

Is Browser Use MCP the same as every “Browser MCP” package?

No. This guide uses the browser-use project and its documented browser-use --mcp command. Check the repository and package name before installing.

Which OpenCode schema should I copy?

Use the schema for your installed release. OpenCode v2 documents named servers under mcp.servers; older documentation may show a flatter layout.

Does the local server need an HTTP port?

No. The documented local integration is a command that OpenCode launches over stdio.

When should I use the cloud endpoint?

Use it when hosted browser execution or Browser Use’s cloud tools fit your workflow. Confirm current authentication, account, pricing, data handling, and terms first.

Can I use ScreenshotNeo for interactive browser automation?

ScreenshotNeo is designed for screenshots, page information, and PDF capture through HTTP or MCP. Use Browser Use when you need multi-step interactive browser actions.

Keep reading