tf_code/docs/playwright-mcp-setup.md

Playwright MCP Setup Guide for tfcode

This guide explains how to run the Playwright MCP server locally using Docker and integrate it with tfcode.

What is Playwright MCP?

Playwright MCP is a Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. It enables AI coding agents to:

• Navigate to web pages
• Click elements and interact with forms
• Capture page snapshots and screenshots
• Run JavaScript in the browser context
• Automate web-based workflows

The key advantage: it uses Playwright's accessibility tree instead of screenshots, making it token-efficient and LLM-friendly without requiring vision models.

Prerequisites

Before starting, ensure you have:

1. Docker Desktop - Download here

   • Make sure Docker daemon is running
   • Verify: docker info

2. tfcode - ToothFairyAI's coding agent

   • Install: npm install -g tfcode
   • Or run from source

Setup Steps

Step 1: Pull the Docker Image

docker pull mcr.microsoft.com/playwright/mcp

This downloads the official Playwright MCP container (~500MB).

Step 2: Verify the Container

Test that the container runs correctly:

docker run --rm mcr.microsoft.com/playwright/mcp --help

You should see the Playwright MCP help output with available options.

Step 3: Configure tfcode

Add the Playwright MCP server to your tfcode configuration.

Option A: Project-level config (opencode.json)

Create or edit opencode.json in your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "--init", "mcr.microsoft.com/playwright/mcp"],
      "enabled": true
    }
  }
}

Option B: Global config (~/.config/opencode/opencode.json)

For all projects, add to your global config:

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "--init", "mcr.microsoft.com/playwright/mcp"],
      "enabled": true
    }
  }
}

Step 4: Verify Connection

Run tfcode MCP list to verify the connection:

# If installed globally
tfcode mcp list

# Or running from source
bun run packages/tfcode/src/index.ts mcp list

Expected output:

✓ playwright connected
    docker run -i --rm --init mcr.microsoft.com/playwright/mcp

Configuration Options

The Docker container supports various options. Pass them as additional arguments in the command array:

Headless Mode (Default for Docker)

{
  "command": ["docker", "run", "-i", "--rm", "--init", "mcr.microsoft.com/playwright/mcp", "--headless"]
}

Browser Selection

{
  "command": ["docker", "run", "-i", "--rm", "--init", "mcr.microsoft.com/playwright/mcp", "--browser", "firefox"]
}

Options: chrome, firefox, webkit, msedge

Viewport Size

{
  "command": [
    "docker",
    "run",
    "-i",
    "--rm",
    "--init",
    "mcr.microsoft.com/playwright/mcp",
    "--viewport-size",
    "1920x1080"
  ]
}

Multiple Options

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "-i",
        "--rm",
        "--init",
        "mcr.microsoft.com/playwright/mcp",
        "--headless",
        "--browser",
        "chromium",
        "--viewport-size",
        "1280x720"
      ],
      "enabled": true
    }
  }
}

Available Tools

Once connected, tfcode can use these Playwright MCP tools:

Tool	Description
browser_navigate	Navigate to a URL
browser_click	Click on an element
browser_type	Type text into an input field
browser_snapshot	Capture accessibility snapshot (preferred over screenshots)
browser_take_screenshot	Take a screenshot of the page
browser_hover	Hover over an element
browser_evaluate	Execute JavaScript in the page
browser_select_option	Select an option in a dropdown
browser_fill_form	Fill multiple form fields at once
browser_press_key	Press a keyboard key
browser_wait_for	Wait for text, element, or time
browser_close	Close the browser
browser_tabs	Manage browser tabs (list, create, close, select)
browser_console_messages	Get console messages
browser_network_requests	List network requests

Usage Examples

Navigate to a Website

Ask tfcode:

Navigate to https://example.com and tell me what's on the page

Form Interaction

Go to https://httpbin.org/forms/post, fill in the form with test data, and submit it

Debugging Web Apps

Navigate to localhost:3000, take a snapshot, and check for any console errors

Automated Testing

Open my local dev server at localhost:5173, click through the login flow, and verify the dashboard loads correctly

Running as a Long-lived Service

Instead of spawning a container per session, you can run Playwright MCP as a persistent service:

docker run -d -i --rm --init \
  --name playwright \
  -p 8931:8931 \
  --entrypoint node \
  mcr.microsoft.com/playwright/mcp \
  cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

Then configure tfcode with a remote connection:

{
  "mcp": {
    "playwright": {
      "type": "remote",
      "url": "http://localhost:8931/mcp",
      "enabled": true
    }
  }
}

Security Notes

• Playwright MCP is not a security boundary - it can access any URL
• In Docker, the browser runs in a containerized environment
• For sensitive operations, consider:
  • Using --allowed-hosts to restrict navigation
  • Running in isolated mode with --isolated
  • Using --storage-state for authentication persistence

Troubleshooting

Container Fails to Start

# Check Docker is running
docker info

# Pull latest image
docker pull mcr.microsoft.com/playwright/mcp

MCP Server Shows "Failed"

# Test the container directly
docker run -i --rm --init mcr.microsoft.com/playwright/mcp

# Check tfcode logs
tfcode debug

Browser Crashes or Times Out

Add timeout configuration:

{
  "command": [
    "docker",
    "run",
    "-i",
    "--rm",
    "--init",
    "mcr.microsoft.com/playwright/mcp",
    "--timeout-navigation",
    "30000"
  ]
}

Permission Denied on Docker Socket

# On Linux, add user to docker group
sudo usermod -aG docker $USER
# Then logout and login again

Additional Resources

• Playwright MCP GitHub
• Playwright Documentation
• MCP Specification
• tfcode Documentation

---

Last updated: 2026-03-27