# BrowserMCP MCP server

> Connects MCP agents to your logged-in Chrome browser to observe tabs, fill forms, and execute automated workflows through a persistent JavaScript workspace.

- Repository: https://github.com/jackwener/BrowserMCP
- Page: https://hostedmcp.org/servers/jackwener/browsermcp
- Transport: stdio
- Stars: 171
- License: Apache-2.0

## Install

### Claude Code

```sh
claude mcp add browsermcp -- npx -y @jackwener/browsermcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "browsermcp": {
      "command": "npx",
      "args": [
        "-y",
        "@jackwener/browsermcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "browsermcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@jackwener/browsermcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"browsermcp","type":"stdio","command":"npx","args":["-y","@jackwener/browsermcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "browsermcp": {
      "command": "npx",
      "args": [
        "-y",
        "@jackwener/browsermcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add browsermcp -- npx -y @jackwener/browsermcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.browsermcp]
command = "npx"
args = ["-y", "@jackwener/browsermcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user browsermcp npx -- -y @jackwener/browsermcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "browsermcp": {
      "command": "npx",
      "args": [
        "-y",
        "@jackwener/browsermcp"
      ]
    }
  }
}
```

## Tools (16)

- `session_finish`: Finish the task: unmarked agent tabs close, user tabs and deliverables release, handoff tabs retain ownership and usable handles. Returns closed/released/retained/failed separately.
- `tabs_list`: List session and unclaimed tabs without claiming, loading or focusing. Continue with cursor alone. Use tabId directly; claim an unclaimed backendId before operating. (read-only)
- `claim_tab`: Acquire an existing user tab. Exactly one selector: backendId, active:true, or unique URL/title. Does not create a tab.
- `open_tab`: Explicitly create a new tab. Prefer navigate_tab to reuse an existing tab.
- `navigate_tab`: Navigate the specified session tab in place. Never creates a tab, including on failure. Reuse its tabId for subsequent operations. For SPA readiness, pass ready (the same conditions as tab.expect) and timeoutMs; DOM settling alone does not guarantee loaded content.
- `close_tab`: Close exactly one session-owned tab. For a user tab, claim it first. Closing is different from releasing control.
- `tabs_close`: Close explicit session tab handles; returns an outcome for each tab, including partial failure. Never targets the current tab implicitly.
- `release_tab`: Leave the tab open and relinquish session control. Its handle becomes unusable until claimed again.
- `tab_observe`: Observe a session tab. Continue captured state using options.cursor. No implicit tab selection. (read-only)
- `tab_act`: Perform one action on an explicit session tab. Input delivery does not prove task completion; observe or verify the resulting page before deciding the next action.
- `doctor`: Runtime status: browser connection, extension features and protocol warning (if versions differ), site/command counts, sessions. A protocol mismatch blocks browser commands until the host and extension are updated. (read-only)
- `sites_search`: Find reusable site commands before implementing the same task with browser actions or scripts. No query: list available sites with sample commands. With a task, site, or domain as query: find matching commands. Results include args[{name,type,required,help,default,choices}] for site_run. Do not invent parameters. (read-only)
- `site_run`: Execute an existing adapter using this session’s browser context. No enable or setup step is required. args must match the args list from sites_search. Invalid args return invalid_args with details.expected. Valid commands execute directly, including writes.
- `docs_get`: No name: compact REPL quickstart and available topics. Pass name for a topic; use member with api-reference for one class or method, e.g. Tab.act or Tab.network. (read-only)
- `js`: Primary browser workspace. Persistent Node REPL: variables, functions, classes and top-level await; use let for reusable bindings. Pre-bound browser, sites, tools, recon. Discover and claim an existing tab first; use helper.navigate_tab({tabId, url}) to reuse it. Only open_tab or browser.tabs.new explicitly creates a tab. helper exposes the same typed commands as MCP, including close_tab. observe returns a compact action map, not HTML; follow nextCursor with tab.observe({cursor}) for remaining captured pages, or scope with {target:{selector:"#main"}}. tab.read() returns an object: use result.text and tab.read(result.next) to continue. For focused content use tab.read({target:{role:"main"}}) or an article locator. Wait for SPA content with tab.expect({target:{selector:"article"},visible:true},{timeoutMs:15000}); use a unique target when multiple articles exist. tab.evaluate defaults to 10000 ms; pass timeoutMs for longer work. Reuse tab across calls; await tab.act({action:"click", target:{ref:"..."}}) with an observed ref, then observe. Batch determined steps and return at new decision points. Await API calls; dispatched API work is drained before returning. Ordinary errors preserve bindings. Last expression is returned; do not use top-level return. nodeRepl.write(value) adds output. Page JS uses tab.evaluate. docs_get with no arguments returns quickstart/topics; api-reference with member:"Tab.act" gives exact types.
- `js_reset`: Stop JavaScript, clear bindings and close explicit subscriptions; browser tabs stay open. pendingCalls reports already dispatched API operations that may still complete. Wait until doctor shows javascript.pendingCalls:0 before more js; inspect the page before retrying actions.

## FAQ

### What can BrowserMCP do with my browser?

It allows MCP clients to search, read pages, fill forms, and navigate through your existing, logged-in browser sessions.

### Which browsers are supported?

While designed for Google Chrome, the local host also supports other Chromium-based browsers like Edge and Brave.

### Does it work with Claude Desktop or Cursor?

Yes, it works with various MCP clients including Claude Desktop, Cursor, Claude Code, and others.

### How is the connection secured?

Connections are local-only, using standard MCP stdio to the launcher and then a Unix domain socket or named pipe to the host.
