Kagami

Claude Code Web exclusive Playwright MCP server. Enables browser automation via JWT authentication proxy.

Overview

This project is designed exclusively for Claude Code Web environment and provides an MCP (Model Context Protocol) server for using Playwright.

Important: This project is designed to work only in Claude Code Web environment. It will not work in local environments or other environments.

Key Features:

Auto-setup functionality (automatically installs required components on first startup)
External access via JWT authentication proxy
Automation using Firefox browser
Automatic CA certificate import
MCP protocol compliant

Architecture

Claude Code → mcp.py → playwright-mcp (Firefox) → proxy.py → JWT Auth Proxy → Internet

mcp.py: MCP server entry point. Responsible for initial setup and launching proxy.py
@playwright/mcp: Playwright MCP server implementation (Node.js)
Firefox: Browser engine
proxy.py: Local proxy server
JWT Auth Proxy: Authentication proxy for external access

Setup

Automatic Setup (Recommended)

The following will be automatically set up on first startup:

certutil installation
@playwright/mcp installation
Firefox installation
Firefox profile creation
CA certificate import
Configuration file generation

Note:

First startup may take 30 seconds or more

Usage

Launch as MCP Server

Configure in .mcp.json and Claude Code will automatically launch it:

{
  "mcpServers": {
    "playwright": {
      "command": "python3",
      "args": [
        "playwright_mcp_claude_code_web/mcp.py"
      ]
    }
  }
}

File Structure

.
├── playwright_mcp_claude_code_web/
│   ├── mcp.py                          # MCP server (uses only standard library)
│   ├── setup_minimal.py                # Minimal synchronous setup
│   ├── setup_mcp.py                    # Full asynchronous setup
│   └── README.md                       # Detailed documentation
├── .mcp.json                           # MCP server configuration
└── README.md                           # This file

Technical Details

Startup Flow

mcp.py uses a two-phase setup approach to avoid timeout issues:

Phase 1: Synchronous Setup (runs before responding)

Minimal Setup (setup_minimal.py)
- Install @playwright/mcp via npm
- Create minimal Firefox configuration file
Fetch Tool List
- Start temporary @playwright/mcp process
- Fetch available tool definitions
- Store tool list for immediate response to tools/list requests
- Terminate temporary process
Start MCP Server
- Begin responding as MCP server
- Return stored tool list for tools/list requests
- Return "setup in progress" error for tools/call requests

Phase 2: Asynchronous Setup (runs in background)

Full Setup (setup_mcp.py - runs in background thread)
- Install certutil (for certificate management)
- Install proxy.py via uv
- Install Firefox browser
- Create Firefox profile (/home/user/firefox-profile)
- Import CA certificates for TLS inspection
- Generate final configuration file
Start Services
- Start proxy.py (localhost:18915)
- Start @playwright/mcp with full configuration
- Begin proxying all requests to @playwright/mcp

Communication Flow (After Setup)

Claude Code sends request to mcp.py via MCP protocol (stdin/stdout)
mcp.py proxies request to @playwright/mcp
@playwright/mcp launches Firefox (proxy setting: localhost:18915)
proxy.py forwards requests to JWT authentication proxy
Access external sites through authenticated proxy

Security

Import CA certificate for TLS inspection into Firefox profile
All HTTPS traffic goes through JWT authentication proxy
Firefox runs with dedicated profile (/home/user/firefox-profile)

Note: Claude Code Web environment performs TLS Inspection on all HTTPS communications for security auditing purposes. This project imports the necessary CA certificates to enable secure browsing within this monitored environment.

References

License

MIT