ChromePlayMCP

A policy-aware security Meta-MCP server integrating Playwright MCP and Chrome DevTools MCP for AI coding assistants, security research agents, and automated web workflows.

Overview

ChromePlayMCP is a security-conscious Meta-MCP server designed to bridge Playwright MCP and Chrome DevTools MCP. Rather than exposing dozens of granular, low-level browser automation commands that pollute LLM context windows and risk policy violations, ChromePlayMCP presents a high-level, semantic tool surface.

It manages a single, shared Chrome instance over the Chrome DevTools Protocol (CDP), enforcing strict target origin boundaries, redacting credential materials, and compiling structured JSON evidence bundles.

Key Features

• Unified CDP Execution: Operates Playwright and Chrome DevTools over a single shared browser instance, ensuring full correlation between user actions, network traffic, DOM updates, and storage states.

• Context-Efficient Tool Surface: Exposes 5 high-level meta-tools instead of 50+ individual primitive browser calls, preserving model context budgets.

• Strict Scope Enforcement: Enforces an explicit origin whitelist policy, rejecting out-of-scope navigation attempts automatically.

• Automated Secret Isolation & Redaction: Reads credentials strictly from system environment variables and redacts passwords, session tokens, authorization headers, and JWT secrets before returning observations.

• Non-Destructive Guarantee: Disallows arbitrary script injection (eval()) and limits browser interaction to policy-reviewed actions.

Feature Comparison

Architecture

       AI Assistant (Claude Desktop / Claude Code / OpenCode / Antigravity / Cursor)
                                        |
                                        v
                               [ ChromePlayMCP ]
            (Scope Guard | Policy Engine | Secret Redactor | Artifact Store)
                                        |
                 +----------------------+----------------------+
                 |                                             |
                 v                                             v
       [ @playwright/mcp ]                          [ chrome-devtools-mcp ]
   (Navigation, Form Submits,                     (Network Tracing, Console,
   Authenticated Journeys)                       DOM Mutations, Storage)
                 |                                             |
                 +----------------------+----------------------+
                                        |
                                        v
                     Chrome Instance (CDP: 127.0.0.1:9222)

Prerequisites

• Node.js: Version 20 LTS or higher.

• Google Chrome: Chrome 144+ recommended, with remote debugging enabled.

• Operating System: Linux, macOS, or Windows (PowerShell).

Quick Start

1. Repository Setup

git clone https://github.com/MauricioDuarte100/ChromePlayMCP.git
cd ChromePlayMCP
npm install
npm run build
cp config/orchestrator.example.json config/orchestrator.json

2. Start Shared Chrome Profile

Launch a dedicated Chrome instance bound to loopback remote debugging on port 9222:

Linux / macOS:

./scripts/start-chrome.sh 9222
export CDP_URL="http://127.0.0.1:9222"

Windows (PowerShell):

.\scripts\start-chrome.ps1 -Port 9222
$env:CDP_URL = "http://127.0.0.1:9222"

3. Configure Authorized Target Scope

Edit config/orchestrator.json to define authorized target origins:

{
  "targets": [
    {
      "id": "target-app",
      "allowedOrigins": ["https://example.com"],
      "allowSubdomains": false
    }
  ]
}

Client Integration Setup

Claude Code (CLI)

Register ChromePlayMCP in Claude Code using the claude mcp add command:

claude mcp add chrome-play-mcp \
  -e ORCHESTRATOR_CONFIG="/absolute/path/to/ChromePlayMCP/config/orchestrator.json" \
  -e CDP_URL="http://127.0.0.1:9222" \
  -- node /absolute/path/to/ChromePlayMCP/dist/index.js

Or reference config/claude-code.mcp.json.

OpenCode Interpreter

Add to .opencode/mcp.json or ~/.config/opencode/mcp.json:

{
  "mcpServers": {
    "chrome-play-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ChromePlayMCP/dist/index.js"],
      "env": {
        "ORCHESTRATOR_CONFIG": "/absolute/path/to/ChromePlayMCP/config/orchestrator.json",
        "CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Or via OpenCode CLI:

opencode mcp add chrome-play-mcp -- node /absolute/path/to/ChromePlayMCP/dist/index.js

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "chrome-play-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ChromePlayMCP/dist/index.js"],
      "env": {
        "ORCHESTRATOR_CONFIG": "/absolute/path/to/ChromePlayMCP/config/orchestrator.json",
        "CDP_URL": "http://127.0.0.1:9222",
        "BB_USERNAME": "research-user",
        "BB_PASSWORD": "research-password"
      }
    }
  }
}

Antigravity / Kimi Code / Codex / AGY CLI

Copy config/kimi.mcp.json to .kimi-code/mcp.json or register via CLI:

kimi mcp add --transport stdio chrome_play_mcp -- node /absolute/path/to/ChromePlayMCP/dist/index.js

For Codex:

codex mcp add chrome_play_mcp --env ORCHESTRATOR_CONFIG=/absolute/path/to/ChromePlayMCP/config/orchestrator.json -- node /absolute/path/to/ChromePlayMCP/dist/index.js

Cursor / VS Code / Windsurf

Add to your project root .mcp.json:

{
  "mcpServers": {
    "chrome-play-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ChromePlayMCP/dist/index.js"],
      "env": {
        "ORCHESTRATOR_CONFIG": "${workspaceFolder}/config/orchestrator.json",
        "CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Meta-Tools Reference

Security Model & Policy Engine

1. Origin Filtering: All requested URLs are validated against allowedOrigins. Out-of-scope targets trigger an immediate policy exception.

2. Credential Protection: Passwords and secrets are passed exclusively via named environment variable references (usernameEnv, passwordEnv). Raw secrets are scrubbed before logging or returning outputs.

3. Non-Destructive Bounds: Disallows execution of arbitrary JavaScript strings or unsafe browser evaluation modes.

4. Local Binding: Chrome remote debugging interfaces are bound exclusively to loopback (127.0.0.1).

Verification & Testing

Verify system integrity using the included TypeScript checks and test suite:

# Perform TypeScript static type checking
npm run check

# Run unit tests
npm test

Documentation Index

• docs/ARCHITECTURE.md: System design, provider execution matrix, and policy engine specifications.

• docs/META_TOOLS.md: Detailed API contracts for meta-tools.

• docs/WORKFLOWS.md: Comprehensive operational workflow examples.

• docs/HARDENING.md: Security hardening and isolation recommendations.

License

Distributed under the MIT License. See LICENSE for details.