arc-mcp

Playwright-style semantic browser automation for Arc

Installation

Claude Desktop

1. Download the latest .mcpb file from releases

2. Open Claude Desktop

3. Go to Settings → Extensions

4. Drag and drop the .mcpb file onto the window

Claude Code

claude mcp add --scope user --transport stdio arc nix run github:andrewgazelka/arc-mcp

Or manually add to your MCP settings:

{
  "mcpServers": {
    "arc": {
      "command": "nix",
      "args": ["run", "github:andrewgazelka/arc-mcp"]
    }
  }
}

Use Cases

Flight Search — Compare prices across airlines, check availability, book tickets

Shopping — Search products, read reviews, add to cart, checkout

Groceries — Navigate store catalog, build cart, schedule delivery

Research — Open multiple sources, extract data, synthesize information

Features

Node.js REPL

Execute automation scripts with full access to the browser API — no predefined tool constraints.

await browser.click({ role: { role: 'button', name: 'Search' } });
await browser.fill({ label: 'Email' }, 'user@example.com');
const tabs = await browser.listTabs();
return tabs.length;

Semantic Locators

Find elements the way users see them — by role, label, text, or placeholder. No more fragile CSS selectors.

await browser.click({ role: { role: 'button', name: 'Search' } });
await browser.fill({ label: 'Email' }, 'user@example.com');
await browser.type({ placeholder: 'Search...' }, 'London');

Smart DOM Tree

Get a structured, semantic representation of the page with only interactive elements.

const structure = await browser.getPageStructure(10);

Available Functions

The browser object provides:

Semantic Actions:

• click(locator, options?) — Click element by role, label, text, placeholder, or CSS

• fill(locator, value, options?) — Fast fill (replaces entire value)

• type(locator, text, options?) — Type character-by-character (triggers autocomplete)

• selectOption(locator, option, options?) — Select dropdown option

Navigation:

• openUrl(url, newTab?) — Open URL in new or current tab

• getCurrentTab() — Get active tab info (title, URL)

• listTabs() — List all open tabs

• switchToTab(tabId) — Switch to tab by index

• closeTab(tabId) — Close tab by index

• reloadTab(tabId?) — Reload tab

• goBack(tabId?) — Navigate back

• goForward(tabId?) — Navigate forward

Page Analysis:

• getPageStructure(maxDepth?, tabId?) — Get semantic DOM tree

Low-Level:

• executeJavaScript(code, tabId?) — Run arbitrary JavaScript

Example Workflow

// Open Google Flights
await browser.openUrl('https://www.google.com/travel/flights');

// Fill origin
await browser.fill({ label: 'Where from?' }, 'San Francisco');

// Type destination (triggers autocomplete)
await browser.type({ placeholder: 'Where to?' }, 'London');

// Click search
await browser.click({ role: { role: 'button', name: 'Search' } });

Architecture

This is a monorepo with three packages:

• @arc-mcp/applescript — Low-level AppleScript bridge for Arc

• @arc-mcp/browser — High-level Node.js API with semantic locators

• arc-mcp-server — MCP server exposing REPL

See ARCHITECTURE.md for detailed design.

Requirements

• macOS

• Arc browser

Development

npm install
npm run build        # Build all packages
npm run typecheck    # Type check all packages
npm run pack         # Create .mcpb bundle

Package Usage

Each package can be used independently:

# Use browser API in your own scripts
npm install @arc-mcp/browser

# Use AppleScript bridge directly
npm install @arc-mcp/applescript

Not affiliated with The Browser Company. Arc is a trademark of The Browser Company.

MIT · Andrew Gazelka