Wsl Chrome MCP

WSL Chrome MCP

Chrome DevTools协议（CDP）服务器 模型上下文协议，专为WSL设计。每个MCP会话在Windows上都有自己的隔离Chrome实例——没有标签冲突，会话之间没有数据泄漏。

主要特点

• 每会话Chrome隔离 --每个MCP客户端会话都会使用临时配置文件启动自己的Chrome进程。会话不能相互干扰或干扰您的个人浏览器。
• 配置文件模式 --您可以选择使用窗口范围的选项卡隔离在会话之间共享单个Chrome实例，从而保留您的登录状态和书签。
• 33个浏览器自动化工具 --导航、输入、屏幕截图、可访问性快照、JavaScript执行、网络监控、性能跟踪、设备仿真。
• 持久CDP连接 --使用自动重试（3次尝试）、PowerShell中继回退和HTTP代理作为最后手段的直接WebSocket连接。
• TUI配置仪表板 --交互式终端用户界面(wsl-chrome-mcp config)用于管理所有设置。
• WSL2镜像网络 --本地支持WSL2的镜像网络模式（本地主机访问Windows）。
• 始终在CDP上 --可选模式，通过注入永久启用Chrome的调试端口 --remote-debugging-port 进入Windows快捷方式和注册表协议处理程序。

安装

# Clone the repository
git clone https://github.com/477174/wsl-chrome-mcp.git
cd wsl-chrome-mcp

# Install with uv (recommended)
uv pip install -e .

添加到您的MCP客户端

克劳德代码：

claude mcp add wsl-chrome-mcp -- uv run wsl-chrome-mcp

手动配置 (~/.config/claude-code/mcp.json 或同等）：

{
  "mcpServers": {
    "wsl-chrome-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/wsl-chrome-mcp", "wsl-chrome-mcp"]
    }
  }
}

可用工具（33）

会话管理（3）

导航（7）

输入（8）

快照和等待（2）

屏幕截图和PDF（2）

脚本（3）

监控（4）

仿真（1）

性能（3）

建筑

┌──────────────────────────────────────────────────────────────────────┐
│                            WSL Linux                                 │
│                                                                      │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │                      wsl-chrome-mcp                            │  │
│  │                                                                │  │
│  │  ┌──────────────┐    ┌──────────────────┐    ┌─────────────┐  │  │
│  │  │  MCP Server   │───>│  Pool Manager    │───>│ Persistent  │  │  │
│  │  │  (FastMCP)    │    │  (chrome_pool)   │    │ CDP Client  │  │  │
│  │  └──────────────┘    └──────────────────┘    └──────┬──────┘  │  │
│  │                                                      │         │  │
│  │  ┌──────────────┐    ┌──────────────────┐           │         │  │
│  │  │  33 Tools     │    │  Config Manager  │           │         │  │
│  │  │  (modular)    │    │  (TOML)          │           │         │  │
│  │  └──────────────┘    └──────────────────┘           │         │  │
│  └──────────────────────────────────────────────────────┼─────────┘  │
│                                                         │            │
│                          CDP over WebSocket              │            │
│                          (port 9222)                     │            │
└─────────────────────────────────────────────────────────┼────────────┘
                                                          │
┌─────────────────────────────────────────────────────────┼────────────┐
│                         Windows Host                     │            │
│                                                          │            │
│  Isolated Mode (default):          Profile Mode:         │            │
│  ┌──────────┐ ┌──────────┐        ┌──────────────────┐  │            │
│  │ Chrome 1  │ │ Chrome 2  │        │ Shared Chrome    │<─┘            │
│  │ (temp     │ │ (temp     │        │ (your profile)   │               │
│  │  profile) │ │  profile) │        │ window-scoped    │               │
│  └──────────┘ └──────────┘        └──────────────────┘               │
└──────────────────────────────────────────────────────────────────────┘

会话模式

隔离模式（默认）

每个MCP会话都会启动一个 单独的Chrome进程 具有临时用户数据目录。会话是完全独立的——不同的Cookie、存储和历史记录。会话结束后，临时配置文件将被删除。

• 不会干扰您的个人Chrome浏览器
• 并发MCP会话之间没有干扰
• 每次清洁状态

[chrome]
profile_mode = "isolated"

配置文件模式

所有会话共享一个 单个Chrome实例 使用您现有的Chrome个人资料。每个会话都有自己的窗口，只跟踪它创建的选项卡。您的登录会话、书签和扩展都可用。

• 跨会话保留登录状态
• 访问您的书签和扩展
• 按窗口隔离的会话（不是按进程隔离的会话）

[chrome]
profile_mode = "profile"
profile_name = "Profile 1"

连接策略

服务器使用具有自动回退的多层连接策略：

1. 直接WebSocket --直接连接到Chrome的CDP WebSocket端点（重试3次，两次尝试之间延迟1秒）
2. PowerShell中继 --如果直接连接失败，则在Windows上使用PowerShell作为WebSocket中继
3. HTTP 代理 --最后，通过HTTP代理CDP命令

连接状态在工具响应中报告(Connected: True/False).即使有 Connected: False （代理模式），所有工具仍能正常工作。

配置

设置存储在 ~/.config/wsl-chrome-mcp/config.toml:

[chrome]
debug_port = 9222         # CDP debugging port
headless = false          # Run Chrome headless
profile_mode = "isolated" # "isolated" or "profile"
profile_name = ""         # Chrome profile name (profile mode only)

[network]
mirrored_networking = true  # WSL2 mirrored networking mode

[cdp]
always_on = false         # Keep CDP enabled permanently via registry

[plugin]
installed = true          # Whether OpenCode plugin is installed

交互式配置

运行TUI仪表板以交互方式配置所有设置：

wsl-chrome-mcp config

TUI提供切换开关、下拉选择器和配置文件检测，并实时预览您的配置。

发展

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests (98 unit tests)
uv run pytest

# Run E2E concurrency test (requires Windows Chrome)
uv run pytest tests/test_isolated_concurrency.py -v

# Lint and format
uv run ruff check .
uv run ruff format .

# Type check
uv run mypy src

故障排除

未找到Chrome

确保Chrome已安装在Windows的以下位置之一：

• C:\Program Files\Google\Chrome\Application\chrome.exe
• C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
• %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe

连接被拒绝

1. 检查Chrome是否正在进行远程调试：

   curl http://localhost:9222/json/version

1. Windows防火墙可能正在阻止端口9222。添加入站规则。

1. 如果使用WSL2而不使用镜像网络，请尝试Windows主机IP：

   curl http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):9222/json/version

已连接：False（代理回退）

这意味着直接WebSocket连接失败，但HTTP代理正在工作。所有工具仍正常工作。要恢复直接连接，请执行以下操作：

1. 确保Chrome正在运行 --remote-debugging-port=9222
2. 检查是否没有其他进程正在使用端口9222
3. 重新启动MCP服务器以重试连接

WSL1与WSL2

此MCP针对WSL2进行了优化。对于WSL1，您可能需要使用 localhost 而不是Windows主机IP：

export WSL_HOST_IP=127.0.0.1

许可证

麻省理工学院

学分

受...启发 chrome开发工具mcp 来自Chrome DevTools团队。

来源

• Chrome开发工具MCP
• Chrome DevTools协议文档
• MCP Python SDK
• 模型上下文协议