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

Capability	Raw Upstream MCP Servers	ChromePlayMCP Orchestrator
Tool Count	50+ low-level primitive tools	5 domain-specific meta-tools
Browser Instance	Independent, disconnected contexts	Single shared Chrome CDP session (port 9222)
Scope Control	Unrestricted origin navigation	Configurable origin whitelist & subdomain policy
Secret Protection	Raw credential passing in prompts	Environment variable references & automated redaction
Output Format	Unstructured DOM snapshots	Structured JSON observations & artifact store

---

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

Meta-Tool	Description
login_and_capture_session	Performs automated authentication via Playwright using environment variables, capturing tokens, cookies, and correlating storage/network signals via DevTools.
map_frontend_attack_surface	Maps forms, scripts, links, storage key names, console signals, and API endpoints for an in-scope page without body downloads or payload generation.
trace_authenticated_user_flow	Executes a bounded, multi-step Playwright user flow inside an active session while DevTools captures newly observed network endpoints.
compare_anonymous_vs_authenticated_behavior	Evaluates the same URL across authenticated and isolated anonymous contexts to identify access control deltas.
export_browser_observations	Compiles a redacted, structured JSON evidence package containing all observations and artifact references.

---

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.