GitHub - yetidevworks/yetibrowser-mcp (original) (raw)

YetiBrowser MCP

YetiBrowser MCP is a fully open-source implementation of the Browser MCP workflow. It links a Node-based MCP server with Chrome/Firefox extensions so Model Context Protocol clients—Codex/Claude Code, Cursor, Windsurf, MCP Inspector, or your own tools—can automate a real browser tab while keeping every byte on your machine and auditable.

Why pick YetiBrowser MCP?

• Transparent and hackable – no blob downloads. Inspect, fork, and extend every component.
• Local-first – the extension talks only to a localhost MCP server; browsing data never leaves your device.
• Cross-browser – shared logic powers both Chrome and Firefox packages (Firefox build is pending better Manifest V3 support, so connection UX may be limited until Mozilla ships full MV3 APIs).
• Developer-focused tooling – richer console capture, DOM diffing, page-state dumps, and full-page screenshots built for debugging and QA.
• Production-friendly – scripts and docs for packaging, publishing, and integrating with IDE workflows.

Repository layout

• packages/shared – shared TypeScript definitions for messages and tool schemas.
• packages/server – the MCP server that bridges MCP clients to a running browser tab.
• extensions/shared – shared extension source (background/popup) and assets.
• extensions/chrome / extensions/firefox – per-browser packaging layers.
• docs/ – workspace commands, publishing checklists, and feature notes.
• scripts/ – helper utilities such as package-extensions.sh for release zips.

MCP Tools Available

• browser_snapshot – capture an accessibility-oriented snapshot of the current page
• browser_snapshot_diff – compare the two most recent snapshots to highlight DOM/ARIA changes
• browser_navigate – load a new URL in the connected tab and return an updated snapshot
• browser_go_back / browser_go_forward – move through history while keeping MCP in sync
• browser_wait – pause automation for a set number of seconds
• browser_wait_for – block until a selector appears (optionally visible) before proceeding
• browser_press_key – simulate a keyboard key press on the focused element
• browser_click – click the element identified by a CSS selector
• browser_hover – hover the pointer over the targeted element
• browser_drag – drag an element onto a drop target for sortable/drag-and-drop UIs
• browser_type – type text (optionally submitting with Enter) into an editable element
• browser_fill_form – fill multiple inputs/selects/checkboxes/radios in a single call
• browser_select_option – choose one or more options in a <select> element
• browser_screenshot – capture a viewport or full-page screenshot via the DevTools protocol
• browser_get_console_logs – return recent console output, including errors with stack traces
• browser_page_state – dump forms, storage keys, and cookies for the connected page
• browser_connection_info – report bridge WebSocket port, connection status, and extension version
• browser_evaluate – run custom JavaScript inside the page and return JSON-serializable results
• browser_handle_dialog – accept or dismiss alert/confirm/prompt dialogs with optional prompt text

MCP Browser Extension Installation

Chrome Browser

• Install the latest Chrome Browser Extension here: https://chromewebstore.google.com/detail/hpedknkjljpopinabjjmljgckhlancni?utm_source=item-share-cb
• Leave it on Automatic connection mode unless you are running multiple instances of YetiBrowser MCP Server

Firefox Browser (not currently available)

• Due to the limited capabilities of Manifest v3 in Firefox stable release, the Firefox extension is on hold until full support is commonly avaialble (outside of Nightly builds).

MCP Server Installation

Codex CLI

• Edit your ~/.codex/config.toml and add the MCP entry:
  [mcp_servers.yetibrowser-mcp]
  command = "npx"
  args = ["-y", "@yetidevworks/server"]
• Restart codex CLI command; you should see yetibrowser-mcp listing under /mcp tools.
• If you want to provide a specific port, use this format for the args entry: args = ["-y", "@yetidevworks/server", "--ws-port", "9010"]

Claude Code

• Make sure the extension is installed and connected to a tab, then start the MCP server with npx -y @yetidevworks/server (or run the locally built CLI).
• Add the server entry to ~/Library/Application Support/Claude/claude_desktop_config.json (see the example in docs/publishing.md).
• Restart claude so it picks up the new MCP server; you should see yetibrowser-mcp listed under the /mcp tools menu once the extension connects.

Other MCP-aware clients

• Any MCP client can connect by spawning the CLI (npx -y @yetidevworks/server) or optionally provide a specific port, e.g. npx -y @yetidevworks/server --ws-port 9010.
• The server exposes the standard MCP transport over stdio, so use whatever configuration mechanism your client supports to run the command above when a tab is connected.

MCP Inspector

• For testing and debugging outside a coding agent.
• npx @modelcontextprotocol/inspector npx -y @yetidevworks/server -- --ws-port 9010 to run and inspect the MCP server in conjunction with the YetiBrowser MCP browser extension.

Troubleshooting

• The CLI walks ports 9010-9020 until it finds a free one, logging switched to when it advances. Pass --ws-port <port> if you want to pin a specific port instead.
• The Browser extension popup mirrors that behaviour: leave it on “Automatic” to track the CLI’s port, or choose “Manual” and enter the port reported by browser_connection_info / the CLI log to override it.
• Simply ask your AI tool about the connection port. For example: what is the yetibrowser mcp connction info?, then set the manual port the port reported.

Documentation & build scripts

• Workspace commands live in docs/workspace-commands.md.
• Publishing steps (npm + extension stores) are in docs/publishing.md.
• Screenshot behaviour is documented in docs/screenshot.md.
• Generate distributable Chrome/Firefox zips with ./scripts/package-extensions.sh (outputs to artifacts/).
• A repository-level privacy policy is available in PRIVACY.md.