@simul8r/mcp

Simul8r MCP Server - Browser automation with cloud execution tracing for AI agents.

Connect your AI coding assistant (Cursor, Claude Desktop, VS Code, Windsurf) to browser automation with automatic execution tracing, video recordings, and screenshots.

Quick Start

Local-Only Mode (No Account Required)

Run browser automation locally without any remote storage:

npx @simul8r/mcp --local-only --output-dir ./recordings

This is perfect for:

• Testing and development
• Privacy-sensitive environments
• Offline usage

With Simul8r Platform

For cloud-synced executions with the Simul8r dashboard:

# Option 1: Browser-based login (interactive)
npx @simul8r/mcp login
npx @simul8r/mcp

# Option 2: MCP Token (recommended for CI/automation)
export SIMUL8R_MCP_TOKEN=kst_your_token_here
export SIMUL8R_ORG_ID=your-org-id
npx @simul8r/mcp

Authentication

Option 1: MCP Token (Recommended)

MCP tokens (kst_*) are long-lived tokens created in the Simul8r dashboard. They're ideal for:

• CI/CD pipelines
• Automated workflows
• Shared team configurations

# Set via environment variables
export SIMUL8R_MCP_TOKEN=kst_your_token_here
export SIMUL8R_ORG_ID=your-org-id
npx @simul8r/mcp

Or in your MCP config:

{
  "mcpServers": {
    "simul8r": {
      "command": "npx",
      "args": ["@simul8r/mcp"],
      "env": {
        "SIMUL8R_MCP_TOKEN": "kst_your_token_here",
        "SIMUL8R_ORG_ID": "your-org-id"
      }
    }
  }
}

Option 2: Browser Login (Interactive)

For personal use, authenticate via browser:

npx @simul8r/mcp login

This stores credentials at ~/.simul8r/credentials.json.

Option 3: Local-Only Mode

Skip authentication entirely for local-only usage:

npx @simul8r/mcp --local-only

Installation

# Run directly with npx (recommended)
npx @simul8r/mcp

# Or install globally
npm install -g @simul8r/mcp

# Or per-project
npm install @simul8r/mcp

Commands

# Start MCP server
npx @simul8r/mcp [options]

# Authenticate with Simul8r
npx @simul8r/mcp login

# Check authentication status
npx @simul8r/mcp status

# Show MCP configuration for your editor
npx @simul8r/mcp config           # All editors
npx @simul8r/mcp config cursor    # Cursor only
npx @simul8r/mcp config claude    # Claude Desktop only
npx @simul8r/mcp config vscode    # VS Code only
npx @simul8r/mcp config windsurf  # Windsurf only

# Log out
npx @simul8r/mcp logout

CLI Options

npx @simul8r/mcp [options]

Options:
  --local-only              Run without remote storage (no auth required)
  -t, --token <token>       Authentication token
  --browser <browser>       Browser: chrome, firefox, webkit, msedge (default: chrome)
  --headless                Run browser in headless mode
  --user-data-dir <path>    Browser profile directory
  --output-dir <path>       Directory for traces, screenshots, videos
  --save-trace              Save Playwright trace files
  --device <device>         Device to emulate (e.g., "iPhone 15")
  --viewport <size>         Viewport size (e.g., "1280,720")
  --base-url <url>          Override Simul8r API base URL
  --no-auto-login           Disable automatic login prompt
  --no-freeze-detect        Disable frozen-frame detection on recordings (FFmpeg)
  -V, --version             Output version number
  -h, --help                Display help

Frozen-frame detection (FFmpeg)

By default, when --output-dir is set and a session recording is uploaded, the MCP runs FFmpeg’s freezedetect filter on the local file and stores segments under execution metadata.video_freeze_segments (start_sec / duration_sec).

• Bundled binary: The ffmpeg-static npm dependency ships a platform FFmpeg for macOS, Linux, and Windows on common architectures.
• Fallback: If the bundled binary is missing or fails, the server tries ffmpeg on your PATH (e.g. brew install ffmpeg).
• Startup: On launch you should see either [Simul8r] FFmpeg OK: <path> or a single line explaining that freeze detection is disabled.
• Override: Set FFMPEG_BIN to a custom binary (see ffmpeg-static), or pass --no-freeze-detect to skip analysis entirely.

Environment Variables

| Variable | Description | |----------|-------------| | SIMUL8R_MCP_TOKEN | MCP token (kst_*) for authentication | | SIMUL8R_ORG_ID | Organization ID for execution tracking | | SIMUL8R_TOKEN | Alternative token variable (fallback) |

Configuration Examples

Cursor (~/.cursor/mcp.json)

Local-only:

{
  "mcpServers": {
    "simul8r": {
      "command": "npx",
      "args": ["@simul8r/mcp", "--local-only", "--output-dir", "./recordings"]
    }
  }
}

With MCP Token:

{
  "mcpServers": {
    "simul8r": {
      "command": "npx",
      "args": ["@simul8r/mcp", "--output-dir", "./recordings"],
      "env": {
        "SIMUL8R_MCP_TOKEN": "kst_your_token_here",
        "SIMUL8R_ORG_ID": "your-org-id"
      }
    }
  }
}

Claude Desktop

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "simul8r": {
      "command": "npx",
      "args": ["@simul8r/mcp", "--output-dir", "./recordings"],
      "env": {
        "SIMUL8R_MCP_TOKEN": "kst_your_token_here",
        "SIMUL8R_ORG_ID": "your-org-id"
      }
    }
  }
}

VS Code (settings.json)

{
  "mcp.servers": {
    "simul8r": {
      "command": "npx",
      "args": ["@simul8r/mcp", "--local-only"]
    }
  }
}

Windsurf (~/.windsurf/mcp.json)

{
  "mcpServers": {
    "simul8r": {
      "command": "npx",
      "args": ["@simul8r/mcp", "--local-only"]
    }
  }
}

Programmatic Usage

import { startServer, createSimul8rServer } from '@simul8r/mcp';

// Local-only mode
await startServer({
  token: 'local-only',
  browser: 'chrome',
  headless: false,
  outputDir: './recordings',
  localOnly: true,
});

// With Simul8r platform
await startServer({
  token: process.env.SIMUL8R_MCP_TOKEN!,
  orgId: process.env.SIMUL8R_ORG_ID,
  browser: 'chrome',
  headless: false,
});

// Custom backend wrapper
import { wrapWithSimul8r } from '@simul8r/mcp';

const myBackend = createMyCustomBrowserBackend();
const simul8rBackend = wrapWithSimul8r(myBackend, {
  token: process.env.SIMUL8R_MCP_TOKEN!,
  baseUrl: 'https://simul8r-ai-backend-1081360848034.us-central1.run.app/api/v1',
});

Features

• Local-Only Mode: Run browser automation without any remote dependencies
• MCP Token Auth: Long-lived tokens for CI/CD and automation
• Browser Login: Interactive OAuth for personal use
• Execution Tracing: Automatic trace streaming to Simul8r platform
• Video Recording: Browser session recordings
• Screenshot Capture: Automatic screenshot uploads
• Multi-Client Support: Works with Cursor, Claude Desktop, VS Code, Windsurf

Requirements

• Node.js 18+
• Optional: Playwright for full browser automation

License

MIT