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

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

Setup

Automatic Setup (Recommended)

The following will be automatically set up on first startup:

1. certutil installation
2. @playwright/mcp installation
3. Firefox installation
4. Firefox profile creation
5. CA certificate import
6. 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)

1. Minimal Setup (setup_minimal.py)

   • Install @playwright/mcp via npm
   • Create minimal Firefox configuration file

2. 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

3. 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)

4. 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

5. Start Services

   • Start proxy.py (localhost:18915)
   • Start @playwright/mcp with full configuration
   • Begin proxying all requests to @playwright/mcp

Communication Flow (After Setup)

1. Claude Code sends request to mcp.py via MCP protocol (stdin/stdout)
2. mcp.py proxies request to @playwright/mcp
3. @playwright/mcp launches Firefox (proxy setting: localhost:18915)
4. proxy.py forwards requests to JWT authentication proxy
5. 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

• Playwright Documentation
• @playwright/mcp GitHub
• MCP Protocol
• proxy.py Documentation

License

MIT