Skip to content
Back to search

opencode-browser

Browser automation plugin for OpenCode AI editor - Control Chrome/Edge with AI, automate web testing, scraping & form filling via MCP integration

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/michaljach--opencode-browser/badge.svg)](/listings/michaljach--opencode-browser)

HTML

<a href="/listings/michaljach--opencode-browser"><img src="/api/listings/michaljach--opencode-browser/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Step 1: Install Browser MCP Extension

1. Visit [https://browsermcp.io/install](https://browsermcp.io/install) 2. Install the Browser MCP extension for your browser (Chrome or Edge) 3. Follow the extension setup instructions

Step 2: Configure OpenCode

Fastest path:

npx opencode-browser init

This creates or updates `./opencode.json` with the required `plugin` and `mcp.browsermcp` entries while preserving any unrelated config you already have.

For a global setup instead of a project-local one:

npx opencode-browser init --global

Create or update your `opencode.json` configuration file. You can create this file in one of two locations:

- **Global configuration** (applies to all projects): `~/.config/opencode/opencode.json` - **Project-specific configuration** (applies to current project only): `./opencode.json` (in your project root)

Learn more about OpenCode configuration at [https://opencode.ai/docs/config](https://opencode.ai/docs/config)

Add this configuration to your `opencode.json`:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-browser"],
  "mcp": {
    "browsermcp": {
      "type": "local",
      "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"],
      "enabled": true
    }
  }
}

This configuration does two things: 1. **Installs the plugin** - OpenCode automatically downloads `opencode-browser` from npm 2. **Configures Browser MCP** - Sets up the MCP server that actually controls the browser

That's it! No manual file copying required. OpenCode handles everything automatically.

The generated command pins the Browser MCP package version to avoid the extra `@latest` resolution step on startup and keep launches reproducible.

If you prefer to preview the generated config without writing it yet:

npx opencode-browser init --print

Alternative: Install Locally (for development/testing)

If you want to modify the plugin or test changes:

**For global installation:**

mkdir -p ~/.config/opencode/plugins
cp src/index.ts ~/.config/opencode/plugins/browser-mcp.ts

**For project-specific installation:**

mkdir -p .opencode/plugins
cp src/index.ts .opencode/plugins/browser-mcp.ts

The plugin will be automatically loaded on OpenCode startup.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 414 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # OpenCode Browser MCP Plugin
  2. An OpenCode plugin that integrates [Browser MCP](https://browsermcp.io) 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.
  3. Works with both **OpenCode 1** (1.18.29+) and **OpenCode 2**.
  4. ## Demo
  5. ![Demo](assets/demo.gif)
  6. ## Features
  7. - Full browser automation support through Browser MCP
  8. - **OpenCode 1 and 2 support** from one package
  9. - **Speed-oriented browser guidance** injected into the model prompt
  10. - **Tool-specific performance hints** for expensive browser actions
  11. - **Fast retry behavior** with no artificial reconnect backoff in the plugin
  12. - Automatic detection of browser-related tasks
  13. - Context preservation for browser state across session compactions
  14. - Seamless integration with OpenCode's existing tools
  15. ## Prerequisites
  16. Before using this plugin, you need:
  17. 1. **Node.js** installed on your system
  18. 2. **OpenCode 1.18.29+ or OpenCode 2** installed and configured
  19. 3. **Browser MCP extension** installed in your browser (Chrome/Edge)
  20. ## Installation
  21. ### Step 1: Install Browser MCP Extension
  22. 1. Visit [https://browsermcp.io/install](https://browsermcp.io/install)
  23. 2. Install the Browser MCP extension for your browser (Chrome or Edge)
  24. 3. Follow the extension setup instructions
  25. ### Step 2: Configure OpenCode
  26. Fastest path:
  27. ```bash
  28. npx opencode-browser init
  29. ```
  30. This creates or updates `./opencode.json` with the required `plugin` and `mcp.browsermcp` entries while preserving any unrelated config you already have.
  31. For a global setup instead of a project-local one:
  32. ```bash
  33. npx opencode-browser init --global
  34. ```
  35. If you prefer to preview the generated config without writing it yet:
  36. ```bash
  37. npx opencode-browser init --print
  38. ```
  39. Or configure it by hand. Create or update your `opencode.json` configuration file. You can create this file in one of two locations:
  40. - **Global configuration** (applies to all projects): `~/.config/opencode/opencode.json`
  41. - **Project-specific configuration** (applies to current project only): `./opencode.json` (in your project root)
  42. Learn more about OpenCode configuration at [https://opencode.ai/docs/config](https://opencode.ai/docs/config)
  43. Add this configuration to your `opencode.json`:
  44. ```json
  45. {
  46. "$schema": "https://opencode.ai/config.json",
  47. "plugin": ["opencode-browser"],
  48. "mcp": {
  49. "browsermcp": {
  50. "type": "local",
  51. "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"],
  52. "enabled": true
  53. }
  54. }
  55. }
  56. ```
  57. This configuration does two things:
  58. 1. **Installs the plugin** - OpenCode automatically downloads `opencode-browser` from npm
  59. 2. **Configures Browser MCP** - Sets up the MCP server that actually controls the browser
  60. That's it! No manual file copying required. OpenCode handles everything automatically.
  61. The generated command pins the Browser MCP package version to avoid the extra `@latest` resolution step on startup and keep launches reproducible.
  62. ### OpenCode 2
  63. 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.
  64. To use the native V2 configuration shape, move the entry from `plugin` to `plugins` and use the V2 MCP shape:
  65. ```jsonc
  66. {
  67. "$schema": "https://opencode.ai/config.json",
  68. "plugins": ["opencode-browser"],
  69. "mcp": {
  70. "servers": {
  71. "browsermcp": {
  72. "type": "local",
  73. "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"],
  74. "disabled": false
  75. }
  76. }
  77. }
  78. }
  79. ```
  80. 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.
  81. 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.
  82. #### Alternative: Install Locally (for development/testing)
  83. If you want to modify the plugin or test changes:
  84. **OpenCode 2:** point the config at your clone. The path must be the package directory, not `src/index.ts`:
  85. ```json
  86. {
  87. "$schema": "https://opencode.ai/config.json",
  88. "plugin": ["file:///absolute/path/to/opencode-browser"]
  89. }
  90. ```
  91. **OpenCode 1, global installation:**
  92. ```bash
  93. mkdir -p ~/.config/opencode/plugins
  94. cp src/index.ts ~/.config/opencode/plugins/browser-mcp.ts
  95. ```
  96. **OpenCode 1, project-specific installation:**
  97. ```bash
  98. mkdir -p .opencode/plugins
  99. cp src/index.ts .opencode/plugins/browser-mcp.ts
  100. ```
  101. The plugin will be automatically loaded on OpenCode startup.
  102. ## Configuration
  103. ### Basic Configuration
  104. The minimal configuration requires only the MCP server setup:
  105. ```json
  106. {
  107. "$schema": "https://opencode.ai/config.json",
  108. "mcp": {
  109. "browsermcp": {
  110. "type": "local",
  111. "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"],
  112. "enabled": true
  113. }
  114. }
  115. }
  116. ```
  117. ### Advanced Configuration
  118. For more control, you can disable Browser MCP tools globally and enable them per agent:
  119. ```json
  120. {
  121. "$schema": "https://opencode.ai/config.json",
  122. "mcp": {
  123. "browsermcp": {
  124. "type": "local",
  125. "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"],
  126. "enabled": true
  127. }
  128. },
  129. "tools": {
  130. "browsermcp_*": false
  131. },
  132. "agent": {
  133. "browser-agent": {
  134. "tools": {
  135. "browsermcp_*": true
  136. }
  137. }
  138. }
  139. }
  140. ```
  141. ### Performance Behavior
  142. The plugin improves Browser MCP speed by shaping how the model uses browser tools:
  143. - Adds system guidance that prefers direct navigation and fewer browser calls
  144. - Annotates expensive tools like snapshots, screenshots, and waits with performance hints
  145. - Preserves fast-resume guidance during session compaction
  146. - Avoids plugin-side reconnect delays so you can retry immediately when the browser extension is ready
  147. ### Environment Variables
  148. If you need to pass environment variables to the Browser MCP server:
  149. ```json
  150. {
  151. "$schema": "https://opencode.ai/config.json",
  152. "mcp": {
  153. "browsermcp": {
  154. "type": "local",
  155. "command": ["npx", "-y", "@browsermcp/mcp@0.1.3"],
  156. "enabled": true,
  157. "environment": {
  158. "BROWSER_MCP_DEBUG": "true"
  159. }
  160. }
  161. }
  162. }
  163. ```
  164. ## Usage
  165. Once installed and configured, you can use browser automation in your OpenCode prompts:
  166. ### Basic Browser Navigation
  167. ```
  168. Navigate to https://github.com and search for "opencode"
  169. ```
  170. ### Form Filling
  171. ```
  172. Go to the contact form at https://example.com/contact and fill in:
  173. - Name: John Doe
  174. - Email: john@example.com
  175. - Message: Hello from OpenCode!
  176. Then submit the form.
  177. ```
  178. ### Web Scraping
  179. ```
  180. Visit https://news.ycombinator.com and get the titles of the top 5 stories
  181. ```
  182. ### Complex Automation
  183. ```
  184. Go to https://example.com/login, log in with the test credentials,
  185. navigate to the dashboard, and screenshot the main metrics panel
  186. ```
  187. ### Prompt Tips
  188. For best results when using browser automation:
  189. 1. **Be specific** about URLs and actions
  190. 2. **Prefer direct URLs** instead of clicking through intermediate pages
  191. 3. **Reuse page state** instead of rechecking the same screen repeatedly
  192. 4. **Ask for verification only when needed** because snapshots and screenshots are slower than targeted extraction
  193. 5. **Specify selectors** when needed (CSS selectors, text content, etc.)
  194. You can also add browser automation guidelines to your `AGENTS.md` file:
  195. ```markdown
  196. ## Browser Automation
  197. When performing browser automation tasks:
  198. - Always confirm the page has loaded before interacting
  199. - Use descriptive selectors (prefer text content over CSS selectors)
  200. - Take screenshots when verification is needed
  201. - Handle errors gracefully (page not found, element not visible, etc.)
  202. - Close tabs when the task is complete
  203. ```
  204. ## Plugin Features
  205. ### Speed-Oriented Guidance
  206. The plugin biases the model toward faster browser workflows:
  207. - Prefers direct `navigate` calls when the destination URL is known
  208. - Reuses the current tab and page state instead of redoing navigation
  209. - Minimizes `snapshot`, `screenshot`, and `wait` calls unless they are actually needed
  210. - Encourages targeted extraction and direct actions over broad inspection
  211. ### Lightweight Connection Recovery
  212. The plugin still detects browser connection issues, but it no longer adds artificial retry sleeps:
  213. - Detects common Browser MCP connection failures from tool output
  214. - Adds immediate retry guidance to the result instead of pausing inside the plugin
  215. - Marks the connection as restored after the next successful browser action
  216. ### Automatic Browser Tool Detection
  217. The plugin automatically detects when Browser MCP tools are being used and applies browser-specific guidance.
  218. ### Session Context Preservation
  219. During session compaction, the plugin preserves browser automation context, ensuring the AI remembers:
  220. - Browser interactions that occurred
  221. - Current browser state considerations
  222. - Fast-resume guidance so it can avoid repeating navigation and inspection
  223. ### Tool Definition Hints
  224. The plugin annotates Browser MCP tool definitions with performance notes, especially for slower tools like snapshots, screenshots, and waits.
  225. ## Troubleshooting
  226. ### Browser MCP Connection Lost
  227. If you see connection errors:
  228. 1. **Check extension status**: Verify the Browser MCP extension is enabled in Chrome
  229. 2. **Re-enable extension**: If you disabled it, simply re-enable it and retry the browser action immediately
  230. 3. **Check browser is running**: Ensure Chrome/Edge is actually running
  231. 4. **Retry after readiness**: The plugin does not add extra backoff delay, so the next attempt can run right away
  232. 5. **Restart only if needed**: Restart OpenCode only if the browser stays unavailable after retrying
  233. The plugin will display messages like:
  234. - `[Browser MCP] The browser connection looks unavailable. Re-enable the Browser MCP extension or browser, then retry.`
  235. - `[Browser MCP] Connection restored. Continuing without extra retry delay.`
  236. ### Browser MCP Not Working
  237. 1. **Check extension is installed**: Open your browser and verify the Browser MCP extension is installed and enabled
  238. 2. **Verify MCP server config**: Ensure your `opencode.json` has the correct MCP configuration
  239. 3. **Check Node.js**: Ensure Node.js is installed: `node --version`
  240. 4. **Test MCP connection**: Restart OpenCode after adding the MCP configuration
  241. ### Plugin Not Loading
  242. 1. **Check the version**: OpenCode 2 needs `opencode-browser` 1.3.0 or newer
  243. 2. **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
  244. 3. **Check file name**: Plugin files should end in `.ts` or `.js`
  245. 4. **Check syntax**: Ensure the TypeScript/JavaScript syntax is valid
  246. 5. **Check logs**: Look for plugin initialization messages in OpenCode output
  247. ### Tools Not Available
  248. 1. **Check MCP server status**: Ensure the Browser MCP server started successfully
  249. 2. **Check tool configuration**: Verify tools aren't disabled in your config
  250. 3. **Restart OpenCode**: Try restarting OpenCode after configuration changes
  251. ### Debug Mode
  252. Enable debug logging by modifying the plugin or checking OpenCode logs:
  253. ```bash
  254. # OpenCode 2: print server logs while running a prompt
  255. opencode run --standalone --print-logs --log-level debug "your prompt"
  256. # OpenCode 1
  257. opencode --verbose
  258. ```
  259. ## Development
  260. ### Building from Source
  261. If you want to modify the plugin:
  262. 1. Clone the repository
  263. 2. Make your changes to `src/index.ts`
  264. 3. Run `npm run typecheck` and `npm test` (covers both the OpenCode 1 and OpenCode 2 entrypoints)
  265. 4. Test locally with a `file://` plugin path (see [Install Locally](#alternative-install-locally-for-developmenttesting))
  266. 5. Submit a PR if you'd like to contribute!
  267. ### Plugin Architecture
  268. 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.
  269. | Purpose | OpenCode 1 hook | OpenCode 2 API |
  270. | --- | --- | --- |
  271. | Inject speed-oriented browser guidance | `experimental.chat.system.transform` | `ctx.session.hook("context")` |
  272. | Add performance hints to Browser MCP tools | `tool.definition` | `ctx.tool.transform` |
  273. | Post-process browser tool results | `tool.execute.after` | `ctx.tool.hook("execute.after")` |
  274. | Preserve browser context | `experimental.session.compacting` | `ctx.session.hook("compaction")` |
  275. | Clean up session state | `event` | `ctx.event.subscribe()` |
  276. 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.
  277. ## Contributing
  278. Contributions are welcome! Please:
  279. 1. Fork the repository
  280. 2. Create a feature branch
  281. 3. Make your changes
  282. 4. Submit a pull request
  283. ## Resources
  284. - [Browser MCP Documentation](https://docs.browsermcp.io/)
  285. - [OpenCode Documentation](https://opencode.ai/docs/)
  286. - [OpenCode Plugin Guide](https://opencode.ai/docs/plugins/)
  287. - [MCP Servers in OpenCode](https://opencode.ai/docs/mcp-servers/)
  288. ## License
  289. MIT License - See LICENSE file for details
  290. ## Support
  291. For issues and questions:
  292. - Browser MCP issues: [Browser MCP GitHub](https://github.com/browsermcp/browser-mcp)
  293. - OpenCode issues: [OpenCode GitHub](https://github.com/anomalyco/opencode)
  294. - Plugin issues: Open an issue in this repository
  295. ## Changelog
  296. See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each version.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.