opencode-browser

Chrome automation plugin for OpenCode via WebSocket and Chrome Extension. Gives AI agents 165+ tools covering tabs, CDP debugging, network interception, visual clicking, session management, accessibility, advanced mouse/keyboard control, testing & mocking, profiling, stealth/anti-fingerprinting, proxy management, form automation, lighthouse audits, screencast recording, and more.

How it works

The system has two parts that talk to each other over a local WebSocket connection:

• MCP Server — a Node.js process that OpenCode connects to via stdio. It exposes all tools to the AI agent and forwards commands over WebSocket to the extension.
• Chrome Extension — a Manifest V3 service worker that receives commands from the MCP server and executes them inside the browser using Chrome APIs and CDP.

OpenCode  <-- stdio -->  MCP Server  <-- WebSocket :3002 -->  Chrome Extension  <-- Chrome APIs -->  Browser

Demo

Extension popup — configure the WebSocket endpoint and toggle the connection:

Demo — OpenCode controlling Chrome in real time:

Installation

1. Install the MCP server

npm install -g @mytai20100/opencode-browser

Or run directly with npx (no install needed):

npx @mytai20100/opencode-browser

2. Register with OpenCode / claude code / codex

Add the server to your OpenCode config (~/.config/opencode/config.json or opencode.json at project root):

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

Or

claude mcp add opencode-browser npx @mytai20100/opencode-browser #Claude code

opencode mcp add opencode-browser npx @mytai20100/opencode-browser #Opencode

codex mcp add opencode-browser npx @mytai20100/opencode-browser #Codex

3. Install the Chrome extension

1. Download or clone this repository.
2. Open Chrome and go to chrome://extensions.
3. Enable Developer mode (top-right toggle).
4. Click Load unpacked and select the extension/ folder.

4. Connect

Click the extension icon in the Chrome toolbar. The default endpoint is ws://localhost:3002. If the MCP server is running on a different machine or port, enter the correct address (e.g. ws://192.168.1.62:3002) and click Save Endpoint. The status indicator turns orange when connected.

5. Setup api & endpoint for Jev/Laya (Optional)

DECISION_ENDPOINT="https://api.typesafe.ai/v1/systemone"
DECISION_API_KEY="sk_xxxxxx"

# Model Configuration
DECISION_MODEL="jev-latest"
DECISION_TIMEOUT_MS=5000

Running locally from source

If you want to run the MCP server from a local clone instead of installing from npm:

git clone https://github.com/mytai20100/opencode-browser
cd opencode-browser/server
npm install
npm run build

Then point OpenCode at the local build by using the absolute path to dist/index.js in your config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "browsermcp": {
      "type": "local",
      "command": ["node", "/absolute/path/to/opencode-browser/server/dist/index.js"],
      "enabled": true
    }
  }
}

Replace /absolute/path/to/opencode-browser with the actual path where you cloned the repo. On macOS and Linux you can get it by running pwd inside the server/ folder. On Windows use the full path with backslashes, e.g. C:\\Users\\you\\opencode-browser\\server\\dist\\index.js.

After saving the config, restart OpenCode. The MCP server will start automatically whenever OpenCode launches.

For the extension, load the extension/ folder from the cloned repo the same way as the regular install: chrome://extensions > Developer mode > Load unpacked > select extension/.

Prompt tips

A few patterns that get the most out of the 165+ available tools:

Always start with the tool graph. Before any multi-step task, ask the agent to call chrome_get_tool_graph with a plain description of the goal. This gives it an ordered execution plan and tells it which tools to skip, saving unnecessary calls.

Use chrome_get_tool_graph with intent "fill in the login form and submit"

Use chrome_get_workflow_context before interacting with a page. It gives the agent a snapshot of all forms, inputs, and buttons so it can build accurate CSS selectors before clicking or typing anything.

Before clicking anything, call chrome_get_workflow_context to map the page first.

Attach the debugger early when working with APIs. If the task involves reading network traffic, attach CDP at the start so requests are captured from the beginning.

Attach the debugger to the current tab, then navigate to the page and capture all API calls.

Prefer chrome_get_content over chrome_get_html for reading pages. It returns clean visible text without markup, which is faster and uses fewer tokens. Only reach for chrome_get_html when you need the raw DOM structure.

Use chrome_find_text_on_screen + chrome_visual_click as a fallback. When a button has no reliable CSS selector, find its text on screen first, then click the returned coordinates.

Find the text "Submit Order" on screen and click it visually.

Save sessions to avoid re-logging in. After a successful login, call chrome_save_session with a name. Restore it at the start of future tasks to skip the authentication flow entirely.

Save the current session as "prod-login" after logging in.

Mock API responses for testing. Use chrome_intercept_request and chrome_mock_response together to inject fake data without touching the backend.

Intercept all requests to /api/orders and return a mocked empty array.

Tools reference

All tools are prefixed with chrome_. The agent can call chrome_get_tool_graph with a plain-text intent to get an optimized execution plan before starting any task — this prevents redundant calls and saves tokens.

Tabs — viewing and querying

| Tool | Description | |------|-------------| | chrome_list_tabs | List all open tabs with id, title, url, active, pinned, muted, audible states | | chrome_get_active_tab | Get info about the currently active tab | | chrome_get_tab_info | Get detailed info about a specific tab by id | | chrome_search_tabs | Search open tabs by title or URL keyword |

Tabs — management

| Tool | Description | |------|-------------| | chrome_navigate | Navigate a tab to a URL (defaults to active tab) | | chrome_new_tab | Open a new tab, optionally with a URL | | chrome_close_tab | Close a tab by id (defaults to active tab) | | chrome_close_tabs | Close multiple tabs by id array | | chrome_switch_tab | Focus a specific tab by id | | chrome_duplicate_tab | Duplicate a tab | | chrome_pin_tab | Pin or unpin a tab | | chrome_mute_tab | Mute or unmute a tab | | chrome_reload_tab | Reload a tab, optionally bypassing cache | | chrome_move_tab | Move a tab to a different position or window |

Windows

| Tool | Description | |------|-------------| | chrome_list_windows | List all open windows with id, state, focused, tab count | | chrome_new_window | Open a new browser window (supports incognito) | | chrome_close_window | Close a browser window by id |

Screenshot

| Tool | Description | |------|-------------| | chrome_screenshot | Capture the visible area as a base64 PNG or JPEG | | chrome_screenshot_element | Capture a specific element by CSS selector | | chrome_screenshot_fullpage | Capture full page with scrolling and stitching | | chrome_pdf_print | Save current page as PDF with custom options |

Page interaction

| Tool | Description | |------|-------------| | chrome_click | Click an element by CSS selector | | chrome_double_click | Double click an element by selector or coordinates | | chrome_right_click | Right click to open context menu | | chrome_middle_click | Middle click (open in new tab) | | chrome_drag_drop | Drag and drop from element A to B | | chrome_type | Type text into an input element by CSS selector | | chrome_hover | Hover over an element by CSS selector | | chrome_select | Select an option in a <select> element | | chrome_scroll | Scroll the page or a specific element by x/y pixels | | chrome_scroll_to | Scroll an element into view | | chrome_key_press | Dispatch a keyboard event (Enter, Escape, Tab, etc.) | | chrome_keyboard_shortcut | Execute keyboard shortcuts (Ctrl+C, Ctrl+V, Ctrl+A, etc.) | | chrome_wait_for_element | Wait until a CSS selector appears in the DOM | | chrome_wait_for_navigation | Wait for page navigation to complete | | chrome_wait_for_network_idle | Wait until no network requests for N milliseconds | | chrome_focus_element | Focus an element without clicking | | chrome_clear_input | Clear an input field | | chrome_select_text | Select/highlight text on the page | | chrome_get_selected_text | Get currently selected text |

Page content

| Tool | Description | |------|-------------| | chrome_get_content | Get the full visible text of the page | | chrome_get_html | Get outer HTML of an element or the full page | | chrome_get_element_info | Get tag, class, text, attributes, bounding box, visibility | | chrome_find_elements | Find all elements matching a CSS selector | | chrome_get_page_info | Get title, URL, scroll position, viewport, links, meta | | chrome_execute_script | Execute arbitrary JavaScript with full DOM access |

Navigation history

| Tool | Description | |------|-------------| | chrome_go_back | Navigate back in the tab's history | | chrome_go_forward | Navigate forward in the tab's history | | chrome_go_home | Navigate the active tab to the new tab page |

Cookies

| Tool | Description | |------|-------------| | chrome_get_cookies | Get all cookies for a given URL | | chrome_set_cookie | Set a cookie for a URL | | chrome_delete_cookie | Delete a specific cookie |

Local storage

| Tool | Description | |------|-------------| | chrome_get_local_storage | Get localStorage value(s) from the current page | | chrome_set_local_storage | Set a localStorage value on the current page | | chrome_clear_local_storage | Clear all localStorage on the current page | | chrome_get_session_storage | Get sessionStorage value(s) from the current page |

History and bookmarks

| Tool | Description | |------|-------------| | chrome_get_history | Search browser history by text query | | chrome_add_bookmark | Add a bookmark | | chrome_search_bookmarks | Search bookmarks by title or URL | | chrome_get_bookmarks | Get all bookmarks in a flat list |

Downloads

| Tool | Description | |------|-------------| | chrome_download | Download a file from a URL | | chrome_list_downloads | List recent downloads, optionally filtered by state |

Tab groups

| Tool | Description | |------|-------------| | chrome_group_tabs | Group tabs with a