# Switch to Direct CDP (recommended)
git checkout direct-chromium
npm install  # Only 89 packages

# Switch back to Puppeteer version
git checkout main  
npm install  # 163 packages

# Install system dependencies
sudo apt update
sudo apt install chromium-browser nodejs npm python3

# Verify Chromium works
chromium-browser --version

git clone https://github.com/nfodor/mcp-chromium-arm64
cd mcp-chromium-arm64
npm install
chmod +x *.py *.sh

# Verify it works immediately after install:
python3 -c "import sys; sys.path.append('.'); import arm64_browser; print('[OK] ARM64 Browser Works!' if 'error' not in arm64_browser.navigate('https://example.com').lower() else '[FAIL] Failed')"

# Quick demo with immediate visible results (30 seconds)
python3 instant_demo.py

# Or comprehensive demo showing all capabilities (2-3 minutes)
./run_demo.sh

# Test MCP server directly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node index.js

# Test Python wrapper
python3 simple_browser.py

# 1) import the exported cookies (replace the [...] with the Cookie-Editor JSON array)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"set_cookies","arguments":{"url":"https://x.com","cookies":[]}}}' | node index.js

# 2) navigate to the page you want — now authenticated
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"navigate","arguments":{"url":"https://x.com/home"}}}' | node index.js

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"set_cookies","arguments":{"url":"https://x.com","cookieHeader":"auth_token=abc123; ct0=def456"}}}' | node index.js

export CHROMIUM_USER_DATA_DIR="$HOME/.mcp-chromium-arm64/profile"

# Test individual tools directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"navigate","arguments":{"url":"https://example.com"}}}' | node index.js

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"evaluate","arguments":{"script":"document.title"}}}' | node index.js

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"screenshot","arguments":{"name":"debug.png"}}}' | node index.js

# Start recording, interact with the page, then stop and encode
# 1. Start screencast
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"start_screencast","arguments":{"format":"jpeg","quality":80,"maxWidth":1280,"maxHeight":720}}}' | node index.js

# 2. Perform actions (navigate, click, fill, etc.)
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"navigate","arguments":{"url":"https://example.com"}}}' | node index.js

# 3. Check recording progress
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"screencast_status","arguments":{}}}' | node index.js

# 4. Stop and encode to MP4
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"stop_screencast","arguments":{"output":"mp4","name":"my-demo"}}}' | node index.js
# Output: /tmp/my-demo.mp4

# Encode as GIF instead (2-pass palette for quality)
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"stop_screencast","arguments":{"output":"gif","name":"bug-repro"}}}' | node index.js
# Output: /tmp/bug-repro.gif

# Or WebM (VP9)
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"stop_screencast","arguments":{"output":"webm"}}}' | node index.js

# Emulate iPhone 16 Pro
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"emulate_device","arguments":{"device":"iphone-16-pro"}}}' | node index.js

# Emulate in landscape mode
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"emulate_device","arguments":{"device":"ipad-pro-13","landscape":true}}}' | node index.js

# Custom viewport with DPR
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"emulate_device","arguments":{"width":390,"height":844,"deviceScaleFactor":3,"mobile":true}}}' | node index.js

# Reset back to desktop
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"reset_emulation","arguments":{}}}' | node index.js

# Navigate to a page, then check console logs
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_console_logs","arguments":{}}}' | node index.js

# Get only errors
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_console_errors","arguments":{}}}' | node index.js

# Check network activity (all requests with status codes)
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_network_logs","arguments":{}}}' | node index.js

# Check for failed requests (4xx/5xx)
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_network_errors","arguments":{}}}' | node index.js

# Clear all logs when done
echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"wipe_logs","arguments":{}}}' | node index.js

# Run all audits at once (accessibility + performance + SEO + best practices + Next.js)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_audit_mode","arguments":{}}}' | node index.js

# Or run individual audits
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_accessibility_audit","arguments":{}}}' | node index.js
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"run_performance_audit","arguments":{}}}' | node index.js
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_seo_audit","arguments":{}}}' | node index.js

# Get full debug info (URL, viewport, memory, timing)
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"run_debugger_mode","arguments":{}}}' | node index.js

# Get info about the currently focused element
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_selected_element","arguments":{}}}' | node index.js
# Returns: tagName, id, className, textContent, value, and a CSS selector

# Manual CDP connection test
node -e "
const { WebSocket } = require('ws');
const { spawn } = require('child_process');

const chrome = spawn('/usr/bin/chromium-browser', [
  '--headless', '--remote-debugging-port=9227'
]);

setTimeout(() => {
  fetch('http://localhost:9227/json')
    .then(r => r.json())
    .then(tabs => {
      console.log('Available tabs:', tabs.length);
      const ws = new WebSocket(tabs[0].webSocketDebuggerUrl);
      ws.on('open', () => {
        console.log('CDP WebSocket connected!');
        ws.send(JSON.stringify({id: 1, method: 'Runtime.evaluate', params: {expression: '2+2'}}));
      });
      ws.on('message', (data) => {
        console.log('CDP Response:', JSON.parse(data));
        chrome.kill();
        process.exit(0);
      });
    });
}, 2000);
"

# Monitor system resources during operation
htop &
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"navigate","arguments":{"url":"https://httpbin.org/delay/5"}}}' | time node index.js

# Check memory usage
ps aux | grep chromium
free -h

# Check if debugging port is accessible
curl -s http://localhost:9222/json | jq '.[] | {id, title, type}'

# Monitor WebSocket traffic (install websocat)
websocat ws://localhost:9222/devtools/page/[TAB_ID] --text -v

# Symptoms: "CDP command timeout" errors
# Check if chrome debugging port is running
lsof -i :9222

# Test manual connection
node -e "
const { WebSocket } = require('ws');
const ws = new WebSocket('ws://localhost:9222/devtools/browser');
ws.on('open', () => console.log('✓ WebSocket OK'));
ws.on('error', (e) => console.log('✗ WebSocket Error:', e.message));
setTimeout(() => process.exit(0), 2000);
"

# Symptoms: Browser won't start or hangs
# Kill any stuck processes
pkill -f chromium-browser
pkill -f remote-debugging-port

# Test chrome startup manually
timeout 10s /usr/bin/chromium-browser --headless --remote-debugging-port=9223 --no-sandbox

# Check chrome logs
journalctl --user -u chromium --since "1 hour ago"

# Debug CSS selectors interactively
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"evaluate","arguments":{"script":"document.querySelectorAll(\"button\").length"}}}' | node index.js

# Get element information
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"evaluate","arguments":{"script":"document.querySelector(\"#mybutton\") ? \"found\" : \"not found\""}}}' | node index.js

# Monitor memory during operation
watch -n 1 'ps aux | grep -E "(chromium|node)" | grep -v grep'

# Chrome memory debugging
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"evaluate","arguments":{"script":"JSON.stringify(performance.memory)"}}}' | node index.js

# Set environment variables for detailed output
export DEBUG=puppeteer:*
export NODE_ENV=development

# Run with detailed Chrome logs
/usr/bin/chromium-browser --headless --enable-logging --log-level=0 --remote-debugging-port=9222

# Create debug version with message logging
cp index.js debug-index.js

# Add to sendCDPCommand method:
# console.log('→ CDP:', JSON.stringify(command));
# console.log('← CDP:', JSON.stringify(response));

node debug-index.js

# Connect regular Chrome DevTools to the headless instance
# 1. Start the MCP server
# 2. Open regular Chrome/Chromium
# 3. Navigate to: chrome://inspect
# 4. Click "Configure..." and add localhost:9222
# 5. Click "inspect" on the page you want to debug

# Direct CDP (v1.3.0)
time echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"evaluate","arguments":{"script":"Date.now()"}}}' | node index.js

# Puppeteer version (v1.2.0)  
git checkout main
time echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"evaluate","arguments":{"script":"Date.now()"}}}' | node index.js

# Before operation
free -h && ps aux | grep -E "(chromium|node)" | grep -v grep

# During operation (run in another terminal)
watch -n 1 'echo "=== $(date) ===" && free -h && echo && ps aux | grep -E "(chromium|node)" | grep -v grep'

// In index.js, add to tools array:
{
  name: 'my_custom_tool',
  description: 'My custom functionality',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string', description: 'Parameter description' }
    },
    required: ['param']
  }
}

// Add to switch statement in CallToolRequestSchema handler:
case 'my_custom_tool':
  return await this.myCustomTool(args.param);

// Implement the method:
async myCustomTool(param) {
  await this.ensureChromium();
  const result = await this.sendCDPCommand('Page.navigate', { url: param });
  return { content: [{ type: 'text', text: `Custom result: ${result}` }] };
}

# Set browser window size (default: 1280,720)
export CHROMIUM_WINDOW_SIZE=1920,1080

# Cap full-page screenshot height in px (default: 32768)
export CHROMIUM_MAX_SCREENSHOT_HEIGHT=32768

# Persistent profile: keep cookies / logins across restarts (default: ephemeral when unset)
export CHROMIUM_USER_DATA_DIR="$HOME/.mcp-chromium-arm64/profile"

# Use a specific Chromium-family binary (Chrome, Edge, Brave, Opera, Vivaldi, Chromium).
# Overrides auto-detection; point it at any Chromium-based browser.
export CHROMIUM_PATH="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"

# Launch a visible (headful) window instead of headless — e.g. to log into a site
# by hand once into a persistent profile (default: headless when unset)
export CHROMIUM_HEADLESS=false

# Cap Chrome's on-disk HTTP cache in bytes (default: 104857600 = 100MB).
# Bounds profile/cache growth, especially with a persistent CHROMIUM_USER_DATA_DIR.
export CHROMIUM_DISK_CACHE_SIZE=104857600

// Modify in startChromium() method:
const customArgs = [
  '--headless',
  '--no-sandbox',
  '--disable-extensions',
  '--disable-plugins',
  '--disable-background-timer-throttling',
  '--disable-backgrounding-occluded-windows',
  '--disable-renderer-backgrounding',
  '--remote-debugging-port=9222',
  '--window-size=1920,1080',        // Custom viewport
  '--user-agent=CustomUA/1.0',      // Custom user agent
  '--disable-web-security',         // For CORS testing
  '--allow-running-insecure-content' // For mixed content
];

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js and Chromium
brew install node chromium --no-quarantine

// Detect platform and set appropriate chrome path
function getChromePath() {
  const platform = process.platform;
  
  switch(platform) {
    case 'linux':
      return '/usr/bin/chromium-browser';
    case 'darwin': // macOS
      // Try multiple possible paths
      const macPaths = [
        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
        '/Applications/Chromium.app/Contents/MacOS/Chromium',
        '/opt/homebrew/bin/chromium'
      ];
      
      for (const path of macPaths) {
        if (require('fs').existsSync(path)) {
          return path;
        }
      }
      throw new Error('Chrome/Chromium not found on macOS');
    case 'win32':
      return 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
    default:
      throw new Error(`Unsupported platform: ${platform}`);
  }
}

// Update startChromium method
async startChromium() {
  const chromePath = getChromePath();
  const platform = process.platform;
  
  // Platform-specific arguments
  const baseArgs = [
    '--headless',
    '--disable-extensions',
    '--disable-plugins',
    `--remote-debugging-port=${debuggingPort}`,
    '--no-first-run',
    '--disable-gpu',
    '--window-size=1280,720'
  ];
  
  // Add Linux-specific sandbox flags
  if (platform === 'linux') {
    baseArgs.push('--no-sandbox', '--disable-setuid-sandbox');
  }
  
  // Add macOS-specific flags if needed
  if (platform === 'darwin') {
    baseArgs.push('--disable-dev-shm-usage');
  }
  
  chromiumProcess = spawn(chromePath, baseArgs);
  // ... rest of method
}

# Remove quarantine flag if downloading manually
sudo xattr -r -d com.apple.quarantine /Applications/Chromium.app

# Or install via Homebrew with no-quarantine flag
brew install chromium --no-quarantine

# Option 1: Use Google Chrome (recommended)
# Download from: https://www.google.com/chrome/
# Path: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

# Option 2: Use Chromium via Homebrew
brew install chromium --no-quarantine
# Path: /opt/homebrew/bin/chromium

# Ensure Chrome has required permissions
# System Preferences > Security & Privacy > Privacy tab
# Grant Camera, Microphone access if needed for specific use cases

node -e "
console.log('Platform:', process.platform);
console.log('Architecture:', process.arch);
const fs = require('fs');

const paths = {
  linux: '/usr/bin/chromium-browser',
  darwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
  win32: 'C:\\\\Program Files\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe'
};

const chromePath = paths[process.platform];
console.log('Expected Chrome path:', chromePath);
console.log('Chrome exists:', fs.existsSync(chromePath));
"

# Test basic functionality across platforms
echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"evaluate\",\"arguments\":{\"script\":\"navigator.platform\"}}}' | node index.js

# Should return the current platform

// Windows-specific chrome path detection
case 'win32':
  const winPaths = [
    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
    process.env.LOCALAPPDATA + '\\Google\\Chrome\\Application\\chrome.exe'
  ];
  // Similar path checking logic...

# Install Claude Code CLI if you haven't already
npm install -g @anthropic-ai/claude-code

# From the project directory after cloning
claude mcp add chromium-arm64 "$(pwd)/mcp-wrapper.sh" --scope user

claude mcp list
# Should show: chromium-arm64: /path/to/mcp-wrapper.sh - ✓ Connected

# Exit current session if in one
exit
# Start fresh session
claude

List available MCP servers and use chromium-arm64 to navigate to https://example.com

Take a screenshot using the chromium-arm64 tool

Use chromium-arm64 to click the button with selector #submit

Fill the email field using chromium-arm64 with test@example.com

Record a screencast of the login flow and save it as a GIF

Emulate an iPhone 16 Pro and take a screenshot of the homepage

Run a full audit on https://example.com using chromium-arm64

You: Use chromium-arm64 to navigate to https://httpbin.org/json and show me what you see

Claude: I'll navigate to https://httpbin.org/json using the chromium-arm64 tool.

[Uses chromium-arm64.navigate tool]

The page displays a JSON object with a slideshow structure containing:
- Author: "Yours Truly"
- Date: "date of publication"
- Title: "Sample Slide Show"
...

import simple_browser

# Navigate to any website
result = simple_browser.browser_navigate("https://example.com")
print(result)  # "Successfully navigated to https://example.com"

# Take a screenshot
screenshot = simple_browser.browser_screenshot("homepage.png")
print(screenshot)  # "Screenshot saved to /tmp/homepage.png"

# Execute JavaScript
title = simple_browser.browser_evaluate("document.title")
print(title)  # Website title

# Extract page content
content = simple_browser.browser_get_content("text")
print(content[:100])  # First 100 chars of page text

graph TB
    A[Claude Code] --> B[MCP Protocol]
    B --> C[ARM64 Browser Server]
    C --> D[System Chromium]
    D --> E[Web Pages]
    
    F[Python Tools] --> C
    G[Direct CLI] --> C

# Test MCP server directly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node index.js

# Verify browser installation
chromium-browser --version

# Check Claude MCP integration
claude mcp list

git clone https://github.com/nfodor/mcp-chromium-arm64
cd mcp-chromium-arm64
npm install
# Ready to use - no development server needed!