An OpenCode plugin that integrates Browser MCP to enable browser automation capabilities within OpenCode. This plugin allows the AI to control a browser, navigate websites, fill forms, click elements, and perform other browser automation tasks.
Works with both OpenCode 1 (1.18.29+) and OpenCode 2.
Demo
OpenCode plugin that integrates Browser MCP for browser automation
2026-11-16
스타
—
도구
—
가동 시간
—
Features
Full browser automation support through Browser MCP
OpenCode 1 and 2 support from one package
Speed-oriented browser guidance injected into the model prompt
Tool-specific performance hints for expensive browser actions
Fast retry behavior with no artificial reconnect backoff in the plugin
Automatic detection of browser-related tasks
Context preservation for browser state across session compactions
Seamless integration with OpenCode's existing tools
Prerequisites
Before using this plugin, you need:
Node.js installed on your system
OpenCode 1.18.29+ or OpenCode 2 installed and configured
Browser MCP extension installed in your browser (Chrome/Edge)
The generated command pins the Browser MCP package version to avoid the extra @latest resolution step on startup and keep launches reproducible.
OpenCode 2
The plugin ships a single package that supports both OpenCode 1 and OpenCode 2. OpenCode 2 reads the plugin's V2 definition and registers the same guidance through its session, tool, and event APIs; existing plugin configuration keeps working because OpenCode 2 normalizes V1 configuration.
To use the native V2 configuration shape, move the entry from plugin to plugins and use the V2 MCP shape:
No runtime dependencies are required: the plugin's imports of the OpenCode plugin type packages are type-only, so it loads under both APIs without installing @opencode/plugin or @opencode-ai/plugin into the plugin folder.
If OpenCode 2 reports Plugin must export a default definition with an id and an effect or setup function, you are running a version older than 1.3.0. Update the plugin (opencode plugin update, or clear OpenCode's package cache) and restart.
Once installed and configured, you can use browser automation in your OpenCode prompts:
Basic Browser Navigation
Navigate to https://github.com and search for "opencode"
Form Filling
Go to the contact form at https://example.com/contact and fill in:
- Name: John Doe
- Email: [email protected]
- Message: Hello from OpenCode!
Then submit the form.
Web Scraping
Visit https://news.ycombinator.com and get the titles of the top 5 stories
Complex Automation
Go to https://example.com/login, log in with the test credentials,
navigate to the dashboard, and screenshot the main metrics panel
Prompt Tips
For best results when using browser automation:
Be specific about URLs and actions
Prefer direct URLs instead of clicking through intermediate pages
Reuse page state instead of rechecking the same screen repeatedly
Ask for verification only when needed because snapshots and screenshots are slower than targeted extraction
Specify selectors when needed (CSS selectors, text content, etc.)
You can also add browser automation guidelines to your AGENTS.md file:
## Browser Automation
When performing browser automation tasks:
- Always confirm the page has loaded before interacting
- Use descriptive selectors (prefer text content over CSS selectors)
- Take screenshots when verification is needed
- Handle errors gracefully (page not found, element not visible, etc.)
- Close tabs when the task is complete
Plugin Features
Speed-Oriented Guidance
The plugin biases the model toward faster browser workflows:
Prefers direct navigate calls when the destination URL is known
Reuses the current tab and page state instead of redoing navigation
Minimizes snapshot, screenshot, and wait calls unless they are actually needed
Encourages targeted extraction and direct actions over broad inspection
Lightweight Connection Recovery
The plugin still detects browser connection issues, but it no longer adds artificial retry sleeps:
Detects common Browser MCP connection failures from tool output
Adds immediate retry guidance to the result instead of pausing inside the plugin
Marks the connection as restored after the next successful browser action
Automatic Browser Tool Detection
The plugin automatically detects when Browser MCP tools are being used and applies browser-specific guidance.
Session Context Preservation
During session compaction, the plugin preserves browser automation context, ensuring the AI remembers:
Browser interactions that occurred
Current browser state considerations
Fast-resume guidance so it can avoid repeating navigation and inspection
Tool Definition Hints
The plugin annotates Browser MCP tool definitions with performance notes, especially for slower tools like snapshots, screenshots, and waits.
Troubleshooting
Browser MCP Connection Lost
If you see connection errors:
Check extension status: Verify the Browser MCP extension is enabled in Chrome
Re-enable extension: If you disabled it, simply re-enable it and retry the browser action immediately
Check browser is running: Ensure Chrome/Edge is actually running
Retry after readiness: The plugin does not add extra backoff delay, so the next attempt can run right away
Restart only if needed: Restart OpenCode only if the browser stays unavailable after retrying
The plugin will display messages like:
[Browser MCP] The browser connection looks unavailable. Re-enable the Browser MCP extension or browser, then retry.
[Browser MCP] Connection restored. Continuing without extra retry delay.
Browser MCP Not Working
Check extension is installed: Open your browser and verify the Browser MCP extension is installed and enabled
Verify MCP server config: Ensure your opencode.json has the correct MCP configuration
Check Node.js: Ensure Node.js is installed: node --version
Test MCP connection: Restart OpenCode after adding the MCP configuration
Plugin Not Loading
Check the version: OpenCode 2 needs opencode-browser 1.3.0 or newer
Check file location: Ensure the plugin file is in the correct directory. On OpenCode 2, a file:// plugin path must point to the package directory
Check file name: Plugin files should end in .ts or .js
Check syntax: Ensure the TypeScript/JavaScript syntax is valid
Check logs: Look for plugin initialization messages in OpenCode output
Tools Not Available
Check MCP server status: Ensure the Browser MCP server started successfully
Check tool configuration: Verify tools aren't disabled in your config
Restart OpenCode: Try restarting OpenCode after configuration changes
Debug Mode
Enable debug logging by modifying the plugin or checking OpenCode logs:
# OpenCode 2: print server logs while running a prompt
opencode run --standalone --print-logs --log-level debug "your prompt"
# OpenCode 1
opencode --verbose
Development
Building from Source
If you want to modify the plugin:
Clone the repository
Make your changes to src/index.ts
Run npm run typecheck and npm test (covers both the OpenCode 1 and OpenCode 2 entrypoints)
Test locally with a file:// plugin path (see Install Locally)
Submit a PR if you'd like to contribute!
Plugin Architecture
The package default-exports one definition with two entrypoints that share the same state and guidance text: id + setup() for OpenCode 2, and server() for OpenCode 1.
Purpose
OpenCode 1 hook
OpenCode 2 API
Inject speed-oriented browser guidance
experimental.chat.system.transform
ctx.session.hook("context")
Add performance hints to Browser MCP tools
tool.definition
ctx.tool.transform
Post-process browser tool results
tool.execute.after
ctx.tool.hook("execute.after")
Preserve browser context
experimental.session.compacting
ctx.session.hook("compaction")
Clean up session state
event
ctx.event.subscribe()
On OpenCode 2, browser tools called from Code Mode are reported on the execute result's nested toolCalls, which the plugin also reads so connection recovery hints still work.