Deploy CBrowser as a remote MCP server for claude.ai custom connectors.

This guide shows how to set up CBrowser on your own server. Your entire team can use it through claude.ai without local installation.

| Auth: OAuth 2.1 + API Keys | Tools: 120 (Demo + Enterprise)

Why Remote MCP?

Local MCP (Claude Desktop)	Remote MCP (claude.ai)
Requires local installation	Zero installation for users
One user per machine	Entire team shares one server
Works offline	Requires internet
Browser runs locally	Browser runs on server

Quick Start

Option 1: Public Demo Server (Rate Limited)

Try CBrowser without any setup:


URL	`https://demo.cbrowser.ai/mcp`
Auth	None required
Rate Limit	Per-account, tier-based: Free 100/hr, Pro 1,000/hr, Enterprise unlimited
Purpose	Evaluation only

Go to claude.ai
Open Settings → Integrations → Custom MCP Servers
Add: https://demo.cbrowser.ai/mcp
Click Connect

Option 2: Deploy Your Own Authenticated Server

For production use with Auth0 OAuth, follow the Deployment Steps below.

Architecture

┌─────────────────┐     HTTPS      ┌─────────────────┐     HTTP      ┌─────────────────┐
│   claude.ai     │ ──────────────>│  Nginx/Caddy    │ ────────────> │ CBrowser MCP    │
│  (Custom MCP)   │   :443         │  Reverse Proxy  │  :3100        │    Server       │
└─────────────────┘                └─────────────────┘               └─────────────────┘
                                          │
                                   ┌──────┴──────┐
                                   │ Cloudflare  │ (optional)
                                   │   or SSL    │
                                   └─────────────┘

Prerequisites

Requirement	Minimum
OS	Ubuntu 20.04+
RAM	2 GB
CPU	2 cores
Storage	10 GB
Node.js	18+
Domain	Required
SSL	Required

Deployment Steps

Step 1: Install CBrowser

# Create directory
sudo mkdir -p /opt/cbrowser
cd /opt/cbrowser

# Install
npm init -y
npm install cbrowser

# Install browsers
npx playwright install chromium firefox webkit
npx playwright install-deps

Step 2: Create Systemd Service

sudo nano /etc/systemd/system/cbrowser-mcp.service

[Unit]
Description=CBrowser Remote MCP Server
After=network.target

[Service]
Type=simple
User=YOUR_USER
Group=YOUR_GROUP
WorkingDirectory=/opt/cbrowser

ExecStartPre=/bin/bash -c 'mkdir -p /home/YOUR_USER/.cbrowser/{sessions,screenshots,videos,har,personas,scenarios,helpers,audit,baselines,browser-state,cache,journeys,performance,visual,tests,repairs,config,visual-baselines,cross-browser,responsive,ab-comparison}'
ExecStart=/usr/bin/node node_modules/cbrowser/dist/mcp-server-remote.js

Restart=on-failure
RestartSec=5

Environment=NODE_ENV=production
Environment=PORT=3100
Environment=HOST=127.0.0.1
Environment=MCP_SESSION_MODE=stateless

# Authentication (choose one or both)
# API Key authentication
Environment=MCP_API_KEY=your-secure-api-key

# Auth0 OAuth (for claude.ai)
Environment=AUTH0_DOMAIN=your-tenant.auth0.com
Environment=AUTH0_AUDIENCE=https://your-domain.com/

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable cbrowser-mcp
sudo systemctl start cbrowser-mcp

Step 3: Configure Nginx

sudo nano /etc/nginx/sites-available/cbrowser-mcp.conf

server {
    listen 443 ssl http2;
    server_name cbrowser-mcp.yourdomain.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.key;

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
        proxy_buffering off;
    }
}

sudo ln -s /etc/nginx/sites-available/cbrowser-mcp.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Step 4: Connect to Claude.ai

With Auth0 OAuth (recommended):

Go to claude.ai → Settings → Integrations → Custom MCP Servers
Add URL: https://cbrowser-mcp.yourdomain.com/mcp
Claude.ai will automatically discover OAuth via /.well-known/oauth-protected-resource
Complete the Auth0 login flow when prompted
The connector will be enabled after successful authentication

With API Key:

Go to claude.ai → Settings → Integrations → Custom MCP Servers
Add URL: https://cbrowser-mcp.yourdomain.com/mcp
Add header: Authorization: Bearer your-api-key
Click Connect

Available Tools

The remote MCP server provides 120 tools. Demo tier: 94 base + 20 enterprise stubs + 6 marketing. Enterprise tier: all 120 fully functional.

Core Tools

Tool	Description
`navigate`	Navigate to URL and capture screenshot
`screenshot`	Take screenshot of current page
`click` / `smart_click`	Click elements with AI retry
`fill`	Fill form fields
`scroll`	Scroll page
`press_key`	Press keyboard keys

Analysis Tools

Tool	Description
`assert`	Natural language assertions
`analyze_page`	Analyze page structure
`extract`	Extract data from page
`hunt_bugs`	Autonomous bug discovery
`chaos_test`	Chaos engineering tests

Testing Tools

Tool	Description
`generate_tests`	Generate test scenarios
`test_suite`	Run natural language tests
`repair_tests`	Auto-repair broken tests
`flaky_check`	Detect flaky tests

Visual Regression

Tool	Description
`visual_baseline`	Capture visual baseline
`visual_compare`	Compare against baseline
`responsive_test`	Test across viewports
`cross_browser_test`	Test across browsers
`ab_compare`	Compare two URLs

Persona Testing

Tool	Description
`journey`	Run autonomous journey
`compare_personas`	Compare user types
`create_persona`	Create custom persona
`list_personas`	List available personas

Session Bridge (API-Free Cognitive Features)

These tools let Claude orchestrate cognitive user simulation without an API key on the server.

Tool	Description
`compare_personas_init`	Initialize comparison session with persona profiles
`compare_personas_record_result`	Record journey outcome for a persona
`compare_personas_summarize`	Generate comparison report from recorded results

Session Management

Tool	Description
`save_session`	Save browser state
`load_session`	Restore browser state
`list_sessions`	List saved sessions

Security Considerations

Authentication

CBrowser supports dual authentication. Both can run at the same time.

Auth0 OAuth (for claude.ai)

OAuth 2.1 with PKCE for secure claude.ai integration.

# Add to systemd service
Environment=AUTH0_DOMAIN=your-tenant.auth0.com
Environment=AUTH0_AUDIENCE=https://your-server.com/

Features:

OAuth 2.1 with PKCE - Secure authorization flow
JWT & Opaque Token Support - Validates both via JWKS and userinfo
30-Minute Token Caching - Avoids Auth0 rate limits
Protected Resource Metadata - /.well-known/oauth-protected-resource

See docs/AUTH0-SETUP.md in the npm package for full configuration.

API Keys (for Claude Code CLI)

Simple API key authentication for programmatic access.

# Single key
Environment=MCP_API_KEY=your-secret-key

# Multiple keys
Environment=MCP_API_KEYS=key1,key2,key3

Usage:

# Bearer token (recommended)
curl -H "Authorization: Bearer your-api-key" https://your-server/mcp

# X-API-Key header
curl -H "X-API-Key: your-api-key" https://your-server/mcp

Public Endpoints (No Auth)

These endpoints are always accessible:

/health - Health check
/info - Server info
/.well-known/oauth-protected-resource - OAuth metadata

Rate Limiting

Add to nginx:

limit_req_zone $binary_remote_addr zone=mcp:10m rate=10r/s;

location / {
    limit_req zone=mcp burst=20 nodelay;
    # ... rest of config
}

Monitoring

Health Check

curl https://your-domain.com/health
# {"status":"ok","version":"18.53.0","auth":true,"auth_methods":{"api_key":true,"oauth":true}}

OAuth Metadata

curl https://your-domain.com/.well-known/oauth-protected-resource
# {
#   "resource": "https://your-domain.com",
#   "authorization_servers": ["https://your-tenant.auth0.com"],
#   "bearer_methods_supported": ["header"],
#   "scopes_supported": ["openid", "profile", "cbrowser:read", "cbrowser:write"]
# }

View Logs

sudo journalctl -u cbrowser-mcp -f

Troubleshooting

Service Won't Start

# Check logs
sudo journalctl -u cbrowser-mcp -n 50

# Common fixes
sudo chown -R $USER:$USER /home/$USER/.cbrowser
npx playwright install

Connection Fails in Claude

Verify URL ends with /mcp
Check SSL certificate: curl -v https://your-domain/health
Ensure Accept header support

Browser Timeout

# Install dependencies
npx playwright install-deps

Full Documentation

Full deployment guide with Cloudflare and Docker setup.

MCP-Server - Local MCP for Claude Desktop
Getting-Started - Basic CBrowser setup
Constitutional-Safety - Safety in automation
Auth0 Setup Guide - See docs/AUTH0-SETUP.md in the npm package

Copyright: (c) 2026 Alexa Eden.

License: MIT License

Contact: [email protected]

Remote MCP Server