Titan MCP - Unified Browser Automation Protocol

A unified Model Context Protocol (MCP) that connects AI agents to multiple browser automation tools.

Overview

Titan MCP provides a unified interface for AI agents to control web browsers using multiple backends:

• Selenium - Traditional browser automation
• Playwright - Modern Chromium automation
• Puppeteer - Node.js browser control
• Browser-Use - AI-powered browser interactions

Installation

# Clone the repository
git clone https://github.com/mrhavens/titan-mcp.git
cd titan-mcp

# Install Python dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Install Node.js dependencies
npm install

# Configure
cp config/mcp.yaml.example config/mcp.yaml
# Edit mcp.yaml with your settings

Configuration

Edit config/mcp.yaml:

browsers:
  chromium:
    enabled: true
    headless: false
    viewport: { width: 1920, height: 1080 }
  
  firefox:
    enabled: false
    headless: true

  webkit:
    enabled: false

automation:
  selenium:
    implicit_wait: 10
    page_load_timeout: 30
    
  playwright:
    slow_mo: 0
    accept_downloads: true
    
  browser_use:
    max_steps: 100
    headless: false

agents:
  openclaw:
    gateway: "ws://192.168.1.64:18789"
    token: "your-gateway-token"
    
  # Connect to witness-zero agents
  witness_zero:
    ollama: "http://192.168.1.64:11434"

Usage

Starting the MCP Server

# Start MCP server
python3 mcp_server.py

# Or with custom config
python3 mcp_server.py --config config/mcp.yaml

Connecting to AI Agents

The MCP exposes WebSocket and HTTP endpoints for agent connections:

# Example: Connect OpenClaw agent
import websocket

ws = websocket.create_connection("ws://localhost:8765/agent")
ws.send('{"action": "navigate", "url": "https://example.com"}')

API Endpoints

Endpoint	Method	Description
/browse	POST	Navigate to URL with optional actions
/screenshot	GET	Take screenshot of current page
/execute	POST	Execute JavaScript in browser
/fill	POST	Fill form fields
/click	POST	Click elements
/ws/agent	WS	WebSocket for agent commands

Available Browsers

Browser	Status	Command
Chrome	✅ Installed	google-chrome
Firefox	✅ Installed	firefox
Chromium	✅ Installed	chromium-browser
Edge	✅ Installed	microsoft-edge
Opera	⚠️ Install issues	-

Text Browsers (Fallback)

Browser	Command
Lynx	lynx
Links2	links2
W3m	w3m

Architecture

┌─────────────────────────────────────────────────────────┐
│                    AI Agents                            │
│  (OpenClaw, Claude, GPT, Ollama, etc.)               │
└──────────────────────┬──────────────────────────────────┘
                       │ WebSocket / HTTP
                       ▼
┌─────────────────────────────────────────────────────────┐
│                   Titan MCP Server                        │
│  ┌──────────────┬──────────────┬──────────────┐         │
│  │   Selenium   │  Playwright  │  Puppeteer   │         │
│  └──────────────┴──────────────┴──────────────┘         │
│  ┌──────────────┬──────────────┐                         │
│  │ Browser-Use │  Text Mode  │                         │
│  └──────────────┴──────────────┘                         │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│                    Browsers                              │
│  Chrome | Firefox | Chromium | Edge | Opera            │
└─────────────────────────────────────────────────────────┘

Environment Variables

# Ollama (local models)
OLLAMA_HOST=http://192.168.1.64:11434

# OpenClaw Gateway
OPENCLAW_GATEWAY=ws://192.168.1.64:18789
OPENCLAW_TOKEN=your-token

# Browser settings
BROWSER_HEADLESS=false
BROWSER_TIMEOUT=30

Examples

Navigate and Screenshot

import requests

# Navigate to URL
response = requests.post("http://localhost:8765/browse", json={
    "action": "navigate",
    "url": "https://github.com/mrhavens",
    "wait_for": "networkidle"
})

# Take screenshot
screenshot = requests.get("http://localhost:8765/screenshot")
with open("screenshot.png", "wb") as f:
    f.write(screenshot.content)

Execute JavaScript

response = requests.post("http://localhost:8765/execute", json={
    "script": "document.title = 'Hello from Titan MCP'",
    "return_value": "document.title"
})

KAIROS Integration

This MCP integrates with the KAIROS ADAMON system for autonomous agent coordination.

Phase Lock Testing

# Run phase lock test with 7 agents
python3 scripts/phase_lock_test.py

License

MIT

Author

Mark Havens / Titan Root Havens