Playwright MCP Server - NixOS Flake

Playwright MCP 服务 - NixOS Flake

一个全面的 NixOS Flake 开发环境，适用于 Playwright MCP（模型上下文协议）服务，完整支持 Chrome 和 Firefox，并支持持久化浏览器配置文件。

功能

• ✅ 完整的 Playwright MCP 服务配置：基于 Microsoft 的官方实现
• ✅ 多浏览器支持：包含 Chrome/Chromium 和 Firefox 浏览器
• ✅ 配置文件持久化：在不同会话之间保留浏览器配置文件
• ✅ 桌面配置文件集成：可从桌面应用导入现有的 Chrome/Firefox 配置文件
• ✅ NixOS 集成：针对 NixOS 正确配置所有依赖项
• ✅ 开发环境：开箱即用的开发 Shell，包含所有工具
• ✅ 兼容 AI Agent：可作为 URL 添加到 AI Agent 的开发环境中

快速开始

使用 direnv（推荐）

1. 克隆此代码仓库，或将 flake.nix 复制到你的项目中
2. 启用 direnv：direnv allow
3. 进入目录时，环境将自动激活

手动激活

# Enter the development shell
nix develop

# Or run the MCP server directly
nix run

用法

运行 MCP 服务

# 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

设置浏览器配置文件

若要使用现有的桌面浏览器配置文件：

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

这会将现有的 Chrome/Chromium 和 Firefox 配置文件复制到 Playwright MCP 目录：

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

配置

此 flake 包含一个可自定义的默认配置文件。主要功能：

• 浏览器支持：Chromium 和 Firefox
• 配置文件持久化：在不同会话之间保存配置文件
• 有头模式：默认显示浏览器窗口
• 完整功能：启用所有 MCP 功能（标签页、PDF、历史记录、等待、文件、安装、测试）

在 AI 开发环境中使用

将此 flake 添加为开发环境 URL：

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

或者用于 Claude Desktop MCP 配置：

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

架构

此 flake 提供：

1. 自定义 Playwright MCP 软件包：使用 NixOS 专用配置封装 Microsoft 的 Playwright MCP 服务
2. 浏览器集成：正确配置支持 Playwright 的 Chromium 和 Firefox
3. 配置文件管理：用于管理浏览器配置文件持久化和桌面集成的脚本
4. 开发环境：包含所有依赖项和实用环境变量的完整 Shell

浏览器配置文件位置

默认位置

• Chrome/Chromium 配置文件：~/.local/share/playwright-mcp/chrome-profile
• Firefox 配置文件：~/.local/share/playwright-mcp/firefox-profile

桌面配置文件来源

设置脚本将在以下位置查找现有配置文件：

• Chrome：~/.config/google-chrome
• Chromium：~/.config/chromium
• Firefox：~/.mozilla/firefox（默认配置文件）

配置选项

MCP 服务支持通过命令行参数进行广泛配置：

--allowed-origins      # Semicolon-separated allowed origins
--blocked-origins      # Semicolon-separated blocked origins
--browser             # Browser to use: chrome, firefox, webkit, msedge
--headless            # Run in headless mode
--user-data-dir       # Custom profile directory
--viewport-size       # Browser viewport size (e.g., "1920,1080")
--device              # Device to emulate (e.g., "iPhone 15")
--proxy-server        # Proxy server configuration
--storage-state       # Path to storage state file
--isolated            # Use isolated (non-persistent) profiles
--vision              # Use screenshot mode instead of accessibility snapshots
--config              # Path to JSON configuration file

故障排除

未找到浏览器

如果出现未找到浏览器的错误：

nix run .#playwright-mcp -- --browser chromium
# or
export PLAYWRIGHT_BROWSERS_PATH=$(nix-build '<nixpkgs>' -A playwright-driver.browsers --no-out-link)

配置文件问题

如果浏览器配置文件无法正常使用：

# Reset profiles
rm -rf ~/.local/share/playwright-mcp/
nix run .#setup-profiles

权限问题

确保配置文件目录可写：

chmod -R u+w ~/.local/share/playwright-mcp/

贡献

此 flake 的设计便于扩展。可贡献的主要方向：

1. 浏览器支持：添加更多浏览器配置
2. 配置文件管理：增强配置文件导入/导出功能
3. 配置：改进配置管理
4. 集成：更好地集成各类 AI 开发环境

许可证

本项目遵循底层 Playwright MCP 服务使用的相同许可证（Apache 2.0）。

相关项目

• Microsoft Playwright MCP - 上游 MCP 服务
• natsukium/mcp-servers-nix - MCP 服务的 Nix 框架
• akirak/nix-playwright-mcp - Playwright MCP 的另一种 Nix 封装