Playwright MCP Server - NixOS Flake

A comprehensive NixOS Flake development environment for the Playwright MCP (Model Context Protocol) server with full Chrome and Firefox support, including persistent browser profiles.

Features

• ✅ Complete Playwright MCP Server Setup: Based on Microsoft’s official implementation
• ✅ Multi-Browser Support: Both Chrome/Chromium and Firefox browsers included
• ✅ Profile Persistence: Maintains browser profiles between sessions
• ✅ Desktop Profile Integration: Can import existing Chrome/Firefox profiles from your desktop
• ✅ NixOS Integration: Properly configured for NixOS with all dependencies
• ✅ Development Environment: Ready-to-use development shell with all tools
• ✅ AI Agent Compatible: Can be added as a URL to development environments for AI agents

Quick Start

Using with direnv (Recommended)

1. Clone this repository or copy the flake.nix to your project
2. Enable direnv: direnv allow
3. The environment will automatically activate when you enter the directory

Manual activation

# Enter the development shell
nix develop

# Or run the MCP server directly
nix run

Usage

Running the MCP Server

# Basic usage (headed mode, persistent profiles)
playwright-mcp-wrapped

# Headless mode
playwright-mcp-wrapped --headless

# Specify browser
playwright-mcp-wrapped --browser firefox

# With custom configuration
playwright-mcp-wrapped --config /path/to/config.json

# Server mode (for remote connections)
playwright-mcp-wrapped --port 8931

Setting Up Browser Profiles

To use your existing desktop browser profiles:

# Run the profile setup script
nix run .#setup-profiles

This will copy your existing Chrome/Chromium and Firefox profiles to the Playwright MCP directories:

• Chrome: ~/.local/share/playwright-mcp/chrome-profile
• Firefox: ~/.local/share/playwright-mcp/firefox-profile

Configuration

The flake includes a default configuration file that can be customized. Key features:

• Browser Support: Both Chromium and Firefox
• Profile Persistence: Profiles are saved between sessions
• Headed Mode: Browser windows are visible by default
• Full Capabilities: All MCP capabilities enabled (tabs, PDF, history, wait, files, install, testing)

Using in AI Development Environments

Add this flake as a development environment URL:

{
  "devEnvironments": {
    "playwright-mcp": {
      "url": "github:benjaminkitt/playwright-mcp-nix"
    }
  }
}

Or for Claude Desktop MCP configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "nix",
      "args": ["run", "github:benjaminkitt/playwright-mcp-nix"]
    }
  }
}

Architecture

This flake provides:

1. Custom Playwright MCP Package: Wraps Microsoft’s Playwright MCP server with NixOS-specific configurations
2. Browser Integration: Properly configured Chromium and Firefox with Playwright support