playwright-sse-mcp-server

This is a service that provides Playwright as an MCP (Model Context Protocol) server. By using this server, you can use Playwright functions from an MCP client.

Prerequisites

• Docker installed
• Docker-compose installed
• A Docker network named mcp-network has been created.

If the mcp-network does not exist, you can create it with the following command:

How to set up and start

1. Clone or download the repository
2. Run the following command in the project root directory:

This will start the server on the default port 3002. Once it's finished, you'll see a message like this:

Configuring a Custom Port

If you want to start the server on a port other than the default port (3002), set PORT environment variable:

This will start the server on the port you specify (4000 in this example):

How to use

Connections from containers participating in the same mcp-network

From other containers participating in the same mcp-network, you can connect to the server with the following URL (where PORT is the server's startup port):

If you are using the default ports:

This allows you to take advantage of Playwright's MCP functionality.

Connecting from the host side

From the host machine, you can connect to the server with the following URL (where PORT is the server's running port):

If you are using the default ports:

Connecting from Roo Code

MCP Servers -> Edit MCP Settings -> Fill in the following ( PORT is the server start port):

If you are using the default ports:

*As of March 27, 2025, Cline does not support SSE and cannot be used.

Connecting from Roo Code in a container environment

From a Roo Code container running in the same Docker Network, configure the MCP as follows:

docker-compose.yml configuration example :

With this setting, you can connect to the playwright-sse-mcp-server container from the Roo Code container and use the browser operation function. By using the container name ( playwright-sse-mcp-server ) as the hostname, name resolution is possible within the Docker Network.

Connecting from Roo Code in a development container environment (via host)

If you want to run Roo Code in a development container and connect to this MCP server via your host machine without joining mcp-network , configure the MCP as follows:

For Docker Desktop (Mac/Windows):

For Linux (example: using the bridge gateway IP):

Note:

• Replace <PORT> with the port number that your MCP server exposes on your host (default: 3002).
• For Linux, replace 172.17.0.1 with your host IP address or the gateway IP address of your Docker bridge network, see the Connecting from Development Containers (via Host) section for more information.

Connecting from a development container (via the host)

If you need to access this MCP server from a development container that is not part of mcp-network (e.g. when it is difficult to change the network due to an existing project), you can connect via the host machine.

With this method, you specify the IP address or special DNS name of the "host machine" from the perspective of your development container, and the port that the MCP server exposes on the host (set by ports in compose.yml , default is 3002).

Destination URL:

Replace <PORT> with the port number on which the MCP server is running.

How to determine <host_ip_or_dns_name> :

• Docker Desktop (Mac/Windows): You can use the special DNS name host.docker.internal .
  • Example: http://host.docker.internal:3002/sse
• Linux:
  • Host IP Address: Use the IP address assigned to a network interface on the host machine (for example, found with ifconfig or ip addr commands).
    • Example: http://192.168.1.10:3002/sse (IP address may vary depending on your environment)
  • Docker bridge network gateway: You can use the gateway IP address of the Docker default bridge network ( bridge ), usually 172.17.0.1 . You can check it with docker network inspect bridge command.
    • Example: http://172.17.0.1:3002/sse

Please note:

• Depending on your host's firewall settings, your development container may not be allowed to access ports on the host.
• Check the port number to use with docker compose ps command or in compose.yml file.

Convenient usage

It is tedious to go to the project directory and run the docker compose command every time. Using the following method, you can easily start and stop the server from anywhere.

Shell script method

This project contains shell scripts to easily start and stop the server and view logs.

1. Clone or download the project:

2. Add the following line to .bashrc (or .zshrc or whatever shell configuration file you're using) to include the shell script:

3. Restart your shell or reload the configuration file:

Now you can use the following command from anywhere:

Basic Usage

• playwright-mcp-start - Starts the server with default settings (port 3002, no restart)
• playwright-mcp-stop - Stop the server
• playwright-mcp-logs - View server logs

Using Persistent Mode

Persistent mode will ensure that the server starts automatically on system reboot:

Using a Custom Port

Combining Persistence Mode with Custom Ports

Specifying a Specific Restart Policy

Getting Help

This method is easier to use because it provides more flexibility in changing settings using flag options, and by separating the shell scripts into separate files, the .bashrc file is simpler and easier to maintain.

Customizing the shell script

The shell script is located at scripts/playwright-mcp.sh . You can edit this file to customize it as needed.

environmental variables

The shell script uses the following environment variables:

• PLAYWRIGHT_MCP_HOME : Project installation directory, if not set it will be automatically detected from the location of the script.

For example, you can specify a custom path by setting an environment variable like this:

Notes

• This server runs Playwright in headless mode
• The server communicates with the MCP client using SSE (Server-Sent Events)