Browse Together MCP

🚀 Playwright Browser Proxy with MCP Server

This project allows you to run a Playwright browser and an MCP server on your desktop. You can start a headed browser (for human interaction) along with a corresponding MCP server, which can control the browser via HTTP API or the MCP server itself.

This project offers two complementary services for browser automation and collaborative browsing:

• Browser Proxy Service: Controls a persistent Playwright browser instance via HTTP. You can log in to the services you use as usual.
• MCP Server: Exposes browser functions to MCP clients (such as Claude Desktop) through the FastMCP framework. It can run within the authentication session you provide, giving your MCP commands more permissions and uses.

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

✨ Features

• Multi-browser Support: Supports Chromium (default) or Firefox.
• Persistent Browser Session: A browser instance runs throughout the service lifecycle.
• Page Management: Lists all active browser pages and closes specific pages.
• Content Manipulation: Fills form fields, clicks elements, retrieves page HTML content, and executes fetch requests in the browser context.

📚 Documentation

This project describes incremental planning steps through a series of documents:

• Initial Design Decisions (Note: The project structure description may be outdated)
• Overview of Browser Proxy Service (Multi-session - History)
• Single-session Architecture Refactoring
• 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 to understand how the project was built.

For more information about our local Sandy, Utah Vibe Coding Group, visit vibe-coders.org.

📦 Installation

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

🔧 Technical Details

Architecture

+----------------+      +--------------+      +------------------+
|                |      |              |      |                  |
| Cline/LLM      | ---- | MCP Server   | ---- | Browser Service  |
| (MCP Client)   |      | (mcp.ts)     | HTTP | (browser.ts)     |
|                |      |              |      |                  |
+----------------+      +--------------+      +------------------+
                               |                       |
                          FastMCP API            Playwright API
                               |                       |
                           Standard Input/Output Stream       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 such as Claude Desktop can use all browser functions through simple tool calls.