browser-mcp is a two-part system: a WebExtension (built with WXT, React, and Tailwind) that runs inside Chrome, Edge, or Firefox, and a Node.js MCP (Model Context Protocol) server that exposes browser capabilities as tools to AI clients like Claude Desktop. The two pieces communicate over a local WebSocket on port 11223, with the server acting as the MCP endpoint and the extension executing browser-side actions.

The problem it solves is bridging AI assistants to the user's live browser session. Rather than spinning up a headless browser (like Playwright-based MCPs do), this project reuses the user's already-authenticated, already-open tabs. That means an AI can summarize the page you're currently reading, restyle it, or search your actual browser history without needing a separate automation runtime.

The intended users are developers experimenting with MCP-capable AI clients who want their assistant to interact with real browsing context. Typical usage: configure the MCP client to spawn `npx @djyde/mcp-browser`, install the extension, grant optional permissions (history, bookmarks), and then issue natural-language commands like 'summarize this page' or 'switch this page to dark mode'.

How it works: the MCP server (`server/src/`) registers tools via the @modelcontextprotocol/sdk and runs a local WebSocket server. When a tool is invoked, the server sends a `call` message with a request ID to the connected extension. The extension's background service worker (`background.ts`) receives the call, dispatches it to `CallHandler`, which uses `browser.tabs`, `browser.scripting`, and `browser.history` APIs to fulfill it, then returns a response over the same socket. Page HTML is likely converted to Markdown server-side via turndown/readability/defuddle dependencies.

Notable patterns: the code is small, clean, and straightforward — a shared enum of methods keeps the extension and server in sync, and permissions like history/bookmarks are optional and user-toggleable via the popup. The WebSocket bind is localhost-only. One minor consideration is that any local process could theoretically connect to ws://localhost:11223 and trigger extension actions, but no authentication is implemented; this is typical for local dev MCP setups but worth noting.