playwright-mcp-hosts

中文文档

Like SwitchHosts for Playwright MCP — custom hosts mapping for browser automation without modifying system /etc/hosts.

Installation

No manual installation required. Run on-demand via npx.

Configure MCP Client

Add the following to your MCP client config (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["playwright-mcp-hosts@latest"]
    }
  }
}

On first run, the config directory ~/.playwright-mcp/ and a default hosts.json will be created automatically.

Config Lookup Order

Config uses a project-first strategy (similar to .editorconfig):

1. Project-level: $CWD/.playwright-mcp/hosts.json — applies to current project only
2. Global: ~/.playwright-mcp/hosts.json — shared across all projects

If a project-level config exists, it takes full precedence and the global config is ignored.

Note: Project-level config relies on the MCP process working directory (process.cwd()) pointing to the project root. To use project-level config, create .cursor/mcp.json in your project (not in the global ~/.cursor/mcp.json), so that Cursor launches the MCP server with the project directory as the working directory.

Project-Level Config Example

1. Create .cursor/mcp.json in the project root:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["playwright-mcp-hosts@latest"]
    }
  }
}

2. Create .playwright-mcp/hosts.json in the project root (consider adding it to .gitignore).

3. Restart the playwright MCP server in Cursor Settings → MCP.

Edit Hosts Config

• Global: edit ~/.playwright-mcp/hosts.json
• Project: edit <project>/.playwright-mcp/hosts.json

Restart the MCP server after editing.

Architecture

Browser requests www.example.com
  → CONNECT 127.0.0.1:18999 (local proxy)
  → Lookup hosts map: www.example.com → 10.0.0.1
  → TCP connect to 10.0.0.1:443
  → Browser completes TLS handshake with target
  → Page loads from the target environment

How It Works

Chromium 146+'s --host-resolver-rules is unreliable (ignored when sharing network service process with system browser). This tool uses a local CONNECT proxy with Playwright MCP's --proxy-server option instead:

1. launch.mjs — Launcher script: loads hosts config, starts proxy, launches Playwright MCP
2. proxy.mjs — Lightweight HTTP CONNECT proxy that redirects connections at the TCP level
3. hosts.json — User config file (project-level or global), supporting remote / local / inline host sources

Dependencies

This package does not bundle @playwright/mcp as a hard dependency. It fetches the latest version on-demand via npx @playwright/mcp@latest at runtime.

Configuration

Full hosts.json example:

{
  "sources": [
    {
      "name": "staging",
      "type": "remote",
      "enabled": true,
      "url": "http://10.0.0.1/hosts",
      "timeout": 10000
    },
    {
      "name": "local hosts file",
      "type": "local",
      "enabled": false,
      "path": "~/.playwright-mcp/test-hosts.txt"
    },
    {
      "name": "inline mappings",
      "type": "inline",
      "enabled": false,
      "mappings": {
        "api.example.com": "10.0.0.100",
        "www.example.com": "10.0.0.101"
      }
    }
  ],

  "ignore_https_errors": true,
  "browser": "msedge",
  "extra_args": []
}

Source Fields

Field	Description
name	Label for log output
type	remote (URL) / local (file) / inline (key-value mappings)
enabled	true to enable / false to disable, like SwitchHosts toggles
url	Remote URL returning a standard hosts file (remote type only)
path	Local hosts file path, supports ~ (local type only)
mappings	{ "hostname": "ip" } object (inline type only)
timeout	Fetch timeout in milliseconds, default 5000 (remote type only)

Global Options

Field	Description	Default
ignore_https_errors	Ignore HTTPS certificate errors (usually needed for staging)	false
browser	Browser type: chrome / msedge / firefox / webkit	chrome
proxy_port	Local proxy port for hosts mapping	18999
extra_args	Additional arguments passed to Playwright MCP	[]

Tip: Use msedge — When system Chrome is running, Playwright's Chrome instance may share its network service process, causing proxy settings to be ignored. Edge runs as a separate process and is not affected.

Usage

Switch Environments

Edit hosts.json, set the target environment's enabled to true and others to false, then restart the MCP server.

{
  "sources": [
    { "name": "staging", "enabled": true, ... },
    { "name": "pre-production", "enabled": false, ... }
  ]
}

Disable Hosts Mapping

Set all sources' enabled to false and restart. The browser will connect directly to production (no proxy).

Multiple Sources

Multiple sources can be enabled simultaneously. Later rules override earlier ones for the same hostname.

Remote Hosts File Format

Remote URLs should return content in standard hosts file format:

# comment
10.0.0.1  www.example.com
10.0.0.1  api.example.com
10.0.0.2  internal.example.com