Browse Together (Playwright) MCP server for AI agents

This project provides a powerful MCP server that allows you to control a Playwright browser instance through HTTP APIs or MCP clients like Claude Desktop. The server maintains a persistent browser session that you can interact with programmatically while still allowing direct human interaction.

Prerequisites

Before using the MCP server, you need to install the necessary dependencies:

Install Playwright Browsers

# 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

Visit the Deno Installation guide for additional installation options.

Getting Started

Starting the Browser Service

Start the browser proxy service:

deno task browser

This launches the browser service on http://localhost:8888 (or another port if specified in your environment).

Choosing a Browser

By default, the service uses Chromium. You can select Firefox instead:

# Using environment variable
BROWSER_TYPE=firefox deno task browser

# Or using CLI flag
deno task browser --browser-type firefox

Interacting with the Browser

There are two ways to interact with the browser:

Method 1: Using the HTTP API

Send HTTP POST requests to control the browser:

Navigate to a URL

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

Click an Element

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

Method 2: Using an MCP Client

Configure the MCP Server

Add the following to your MCP client configuration (e.g., in claude_desktop_config.json):

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

Alternatively, you can start the MCP server directly:

deno task mcp

Using the MCP Tools

You can then use natural language to control the browser from your MCP client:

Let's browse to jsr.io together.

Available MCP Tools

The MCP server provides these capabilities:

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

Named Tabs

The browser service supports managing multiple tabs (pages) within a single browser session. Each tab can be referenced by a unique ID:

# Create or use a tab named "search"
curl -X POST http://localhost:8888/api/browser/search \
  -H "Content-Type: application/json" \
  -d '{"action":"goto","url":"https://google.com"}'

# Create or use another tab named "docs"
curl -X POST http://localhost:8888/api/browser/docs \
  -H "Content-Type: application/json" \
  -d '{"action":"goto","url":"https://developer.mozilla.org"}'

This allows you to work with multiple pages simultaneously within the same browser session.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect