Browse Together MCP

Playwright Browser Proxy with MCP Server

A Playwright browser and MCP Server on your desktop. You can spin up a headful browser (for human interaction) and an accompanying MCP server that can be used to control the browser via HTTP API or MCP server.

This project provides two complementary services for browser automation and co-browsing:

- A Browser Proxy Service that controls a persistent Playwright browser instance via HTTP. Let's you log in to services you use, like you normally would.
- An MCP Server that exposes browser functionality to MCP clients (like Claude Desktop) via the FastMCP framework. Can operate inside the authenticated session you provide, giving your MCP commands more power and usefulness as an authenticated user.

Both services are built with Deno and TypeScript and work together seamlessly.

Features

- Multiple Browser Support: Run with either Chromium (default) or Firefox.
- Persistent Browser Session: A single browser instance runs for the lifetime of the service.
- Named Tabs: Control multiple pages (tabs) within the single browser session using unique IDs.
- HTTP API: Interact with the browser using simple JSON commands over HTTP.
- MCP Integration: Use the browser through Cline, Windsurf, Claude Desktop, or other MCP clients.
- Type Safety: Uses Zod for robust validation of incoming commands.
- Secure your browser proxy service (HTTP) endpoint with an API token.

Note: Currently supports Mac OS, but can be extended to other platforms with minor changes.

Is this Computer Use / Operator?

No, not at this time. This is a (headful) web browser that behaves like a normal human-controlled browser, but also allows you to control your session via HTTP API or MCP client. While you CAN get screenshots, pull down docs, etc., this is not a Computer Use / Operator service.

Think of it like MCP-based remote control of a browser session, for pulling down documentation or other tasks while you code.

Core Components

Browser Service:
browser.ts: The main browser proxy service implementation
types.ts: Defines the command structures and types using Zod

MCP Server:
mcp.ts: FastMCP implementation that connects to the browser service

   # Install all browsers
   npx playwright install
# Or install specific browsers

   npx playwright install chromium

   npx playwright install firefox

   

   curl -fsSL https://deno.land/install.sh | sh
   

   deno task browser

   

   {
	   "mcpServers": {
		   "browse-together": {
			   "command": "deno",
			   "args": ["run", "-A", "/Users/duane/Projects/browse-together-mcp/mcp.ts"]
	     },
     }
   }
   

   deno task mcp
   

# Use Firefox via environment variable
BROWSER_TYPE=firefox deno task browser
Or via CLI flag
deno task browser --browser-type firefox

curl -X POST http://localhost:8888/api/browser/myTab \
  -H "Content-Type: application/json" \
  -d '{"action":"goto","url":"https://example.com"}'

curl -X POST http://localhost:8888/api/browser/myTab \
  -H "Content-Type: application/json" \
  -d '{"action":"click","selector":"#submit-button"}'

{
  "mcpServers": {
    "browse-together": {
      "command": "/path/to/deno", 
      "args": [
        "run",
        "--allow-read",
        "--allow-net",
        "--allow-env",
        "--allow-sys",
        "/path/to/browse-together-mcp/mcp.ts"
      ],
      "env": {
        "PORT": "8888" 
      }
    }
  }
}

Let's browse to jsr.io together.

goto: Navigate to a URL
click: Click on an element
fill: Fill a form field
content: Get the page HTML content
fetch: Execute a fetch request in the browser context
listPages: List all active browser pages
closePage: Close a specific page

Documentation

This project was vibe-coded via a series of documents describing incremental planning steps:

Initial Design Decisions (Note: Project structure description may be outdated)
Browser Proxy Service Overview (Multi-Session - Historical)
Single-Session Architecture Refactor
Type Safety Plan (Zod)
Page Resilience Plan
Libraries Used
Testing Strategy
Configuration
Security Considerations
Deno Best Practices
MCP Server Implementation Plan
FastMCP Refactoring

Some of these steps may be outdated or no longer relevant, but are included as a reference and for insight into how the project was built.

See also vibe-coders.org for more information about our local vibe-coding group in Sandy, UT.

Development

Run Browser Proxy: deno task browser
Run MCP Server: deno task mcp
Format Code: deno fmt
Check Dependencies: deno check --all browser.ts mcp.ts types.ts

Architecture

+----------------+      +--------------+      +------------------+
|                |      |              |      |                  |
| Cline/LLM      | ---- | MCP Server   | ---- | Browser Service  |
| (MCP Client)   |      | (mcp.ts)     | HTTP | (browser.ts)     |
|                |      |              |      |                  |
+----------------+      +--------------+      +------------------+
                               |                       |
                          FastMCP API            Playwright API
                               |                       |
                           STDIO/SSE            Chromium Browser

The system works as follows:

1. The Browser Service (browser.ts) manages a persistent Chromium browser instance using Playwright
2. The MCP Server (mcp.ts) provides a standard MCP interface using FastMCP
3. The MCP server forwards commands to the browser service via HTTP
4. MCP Clients like Claude Desktop can use all browser functionality through simple tool calls