home / mcp / browse together mcp server

Browse Together MCP Server

Provides a headful browser session exposed via MCP for authenticated, scripted control.

Installation

Add the following to your MCP client configuration file.

Configuration

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

Browse Together MCP provides a headful Playwright browser paired with an MCP Server on your desktop. You run a persistent browser session that you can control via HTTP API or MCP clients, enabling scriptable tasks and co-browsing while you work in a real browser session.

How to use

You will run two services: a Browser Service that keeps a single Playwright browser instance alive and accessible over HTTP, and an MCP Server that exposes that browser functionality to MCP clients. Start the Browser Service first to obtain a reachable API, then launch the MCP Server so you can issue high‑level browser actions through your MCP client.

With an MCP client, you can perform a sequence of operations such as navigating to URLs, clicking elements, filling forms, and retrieving page content. The system supports multiple browser tabs within one persistent browser instance so you can manage several pages concurrently using unique tab IDs. The HTTP API is simple JSON over HTTP, and the MCP integration lets you use familiar MCP tools to drive the browser actions.

How to install

Prerequisites: you need a Deno runtime and Playwright browser binaries. Install Playwright browsers, then install Deno. After that, you will run two tasks: one to start the Browser Service and one to start the MCP Server.

# Install all browsers
npx playwright install

# Or install specific browsers
npx playwright install chromium
npx playwright install firefox

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

# Verify Deno is available
deno --version

Start the Browser Service to begin listening for browser control requests. The service runs on http://localhost:8888 by default unless you override the port in your environment.

deno task browser

Then start the MCP Server to expose browser functionality to MCP clients.

deno task mcp

Configure your MCP client with a server entry that points to the MCP runner and forwards to the local MCP process. Create a configuration entry that runs the MCP server using Deno and passes the required flags and the path to the MCP script.

{
  "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"
      }
    }
  }
}

Additional setup and configuration

Security: the HTTP endpoint for the browser proxy should be secured with an API token to prevent unauthorized access. Ensure you configure a strong token and limit access to trusted networks.

If you need to change the browser type, you can select Chromium (default) or Firefox by setting the BROWSER_TYPE environment variable or using the browser type flag when you start the Browser Service.

Troubleshooting: if the MCP Client cannot reach the MCP Server, verify that the PORT matches between the MCP client configuration and the MCP server, and confirm that the Browser Service is running and reachable at the expected HTTP endpoint.

Architecture and endpoints

The system consists of a Browser Service that maintains a persistent Playwright browser instance, and an MCP Server that forwards MCP commands to the Browser Service via HTTP. MCP Clients like Claude Desktop interact with the MCP Server to perform browser actions.

Tools exposed to MCP clients

The MCP server provides a set of tools that map to common browser interactions. These tools enable you to navigate, interact with elements, and retrieve page content.

Available tools

goto

Navigate the browser to a specified URL within a named tab.

click

Click an element matching a CSS selector in the current tab.

fill

Fill a form field by selector with the provided value.

content

Retrieve the current HTML content of the page.

fetch

Execute a fetch request within the browser context and return the response.

listPages

List all active browser pages (tabs) with their identifiers.

closePage

Close a specific browser page by its identifier.