comet-mcp

Give Claude Code a browser that thinks.

An MCP server that connects Claude Code to Perplexity Comet - enabling agentic web browsing, deep research, and real-time task monitoring.

Why?

Existing web tools for Claude Code fall into two categories, both with limitations:

1. Search APIs (Tavily, Perplexity API, WebFetch)

Return static text. No interaction, no login, no dynamic content. Great for quick lookups, but can't navigate complex sites or fill forms.

2. Browser Automation (browser-use, Puppeteer MCP, Playwright MCP)

Can interact with pages, but use a one-agent-do-all approach: the same reasoning model that's writing your code is also deciding where to click, what to type, and how to navigate. This overwhelms the context window and fragments focus.

3. Comet MCP: Direct Control + AI Delegation

Comet MCP gives you both. Direct DOM interaction for deterministic tasks (clicking, typing, form filling) AND delegation to Perplexity Comet for AI-powered research and complex browsing.

• Direct mode — comet_interact and comet_navigate give Claude instant, precise control over any web page via CDP. No AI middleman. Click buttons, fill forms, read content in milliseconds
• AI mode — comet_ask delegates to Perplexity for research, summarization, and complex browsing decisions
• Sidecar mode — comet_ask with sidecar: true keeps the current page visible and uses the Perplexity Assistant sidebar for page-aware Q&A
• Result: Deterministic precision when you need it, AI intelligence when you want it

For full toolkit installation, see the canonical install guide. Run npx comet-browser-automation install from any compatible repo to set up all configuration automatically.

Quick Start

1. Configure Claude Code

Add to ~/.claude/settings.json or .mcp.json:

{
  "mcpServers": {
    "comet-bridge": {
      "command": "npx",
      "args": ["-y", "@shawnowen/comet-mcp"]
    }
  }
}

2. Install Comet Browser

Download and install Perplexity Comet.

That's it! The MCP server automatically launches Comet with remote debugging when needed.

3. Use in Claude Code

You: "Use Comet to research the top AI frameworks in 2025"
Claude: [delegates to Comet, monitors progress, returns results]

You: "Log into my GitHub and check my notifications"
Claude: [Comet handles the login flow and navigation]

Tools (26)

Direct Interaction (2) — No AI, pure CDP

| Tool | Description | |------|-------------| | comet_interact | Click, type, fill, check/uncheck, select, scroll, extract text, or run JS on the active page. Supports chaining multiple actions in one call | | comet_navigate | Navigate the active tab to any URL (QBO, Mercury, GitHub, etc.) without opening Perplexity |

comet_interact actions: click, type, fill, press, check, uncheck, select, scroll, wait, extract, evaluate

AI-Assisted Browsing (9)

| Tool | Description | |------|-------------| | comet_connect | Connect to Comet (auto-starts if needed) | | comet_ask | Send a task to Perplexity and wait for response. Use sidecar: true to keep current page and ask via the assistant sidebar | | comet_poll | Check progress on long-running tasks | | comet_stop | Stop current task | | comet_screenshot | Capture current page | | comet_mode | Switch modes: search, research, labs, learn | | comet_shortcut | Trigger a Comet Query Shortcut | | comet_read_page | Extract page as accessibility tree + clean text | | comet_wait_for_idle | Wait for network activity to settle |

Tab Groups (1)

| Tool | Description | |------|-------------| | comet_tab_groups | Manage Chrome tab groups (list, create, update, delete, archive, restore) |

Lifecycle (4)

| Tool | Description | |------|-------------| | comet_lifecycle_start | Register a new lifecycle run | | comet_lifecycle_complete | Mark a run as completed | | comet_lifecycle_abort | Abort a run with optional reason | | comet_lifecycle_update | Update run metadata |

Lifecycle tools are binding-aware: start attaches the run ID to the active or supplied Codex window binding, complete transitions the binding to completed, and abort transitions it to stale.

Orchestration (3)

| Tool | Description | |------|-------------| | comet_task_status | Get unified status (session manifest + extension events + lifecycle) | | comet_delegate | High-level task dispatch with direct Codex binding creation/reuse, URL, and lifecycle setup | | comet_observe | Passively observe browser state, binding owners, and stale/conflict/unbound windows without disrupting active agents |

Parity and Workflow Tools (6)

| Tool | Description | |------|-------------| | comet_pdf | Generate PDF from current page or URL | | comet_scrape | Extract structured data: text, tables, JSON-LD, lists, attributes, multi-element content | | comet_network | Capture network traffic, block URL patterns, intercept and mock API responses | | comet_monitor | Monitor current page or URL for content changes with baselines, diffs, screenshots, and notifications | | comet_automate | Multi-step browser workflows with assertions and variables | | comet_domain | Domain playbooks for QBO, Mercury, GitHub, Google, and SALT |

Codex Window Bindings

Comet MCP routes multi-agent browser work through Codex window bindings. Each binding records the owning Codex session, repo/worktree, branch, windowId, tabGroupId, targetId, sidecar context key, lifecycle run IDs, and status.

Binding rules:

• Normal session agents can operate only on their own binding.
• Worktree and fleet orchestrators can observe wider scopes, but cross-session mutation requires explicit target binding, reason, and audit.
• comet_task_status, comet_peek, sidecar artifacts, lifecycle transitions, and delegation all resolve through the binding index instead of the currently focused window.
• comet_delegate no longer shells out to the legacy session controller. It creates or reuses a binding directly and returns bindingId, windowId, tabGroupId, and dispatchStatus.

Focus-independent routing means browser actions use the resolved binding's targetId, windowId, and tabGroupId, not whatever Comet window happens to be frontmost. Orchestrator-only cross-session actions must carry the target binding and audit reason so ordinary agents cannot accidentally mutate another agent's window.

Choosing the Right Tool

| Task | Use | Why | |------|-----|-----| | Click buttons, fill forms | comet_interact | Direct CDP, milliseconds | | Navigate to a URL | comet_navigate | Immediate, no AI | | Read page content | comet_read_page | Structured a11y tree | | Research a topic | comet_ask | Perplexity's strength | | "Summarize this page" | comet_ask(sidecar: true) | Sidecar sees active tab | | Take a screenshot | comet_screenshot | Direct CDP capture |

Tab Groups

Control Comet's native Chrome tab groups programmatically — create, rename, recolor, collapse, and delete groups.

Requires a one-time extension install (included in the extension/ directory):

1. Open comet://extensions in Comet
2. Enable Developer mode (top-right toggle)
3. Click Load unpacked → select the extension/ folder from this repo
4. The "Comet Tab Groups Bridge" extension appears

How it works: CDP cannot access Chrome's tab group API. The included MV3 extension provides tabGroups permission, and comet-mcp connects to the extension's service worker via CDP to evaluate chrome.tabGroups.* calls directly. No native messaging host needed.

Claude Code → MCP Server → CDP → Extension Service Worker → chrome.tabGroups API → Comet UI

Available actions:

| Action | Parameters | Description | |--------|-----------|-------------| | list | — | List all tab groups (id, title, color, collapsed state) | | list_tabs | — | List all tabs with their group assignments | | create | tabIds, title?, color? | Group tabs and optionally name/color them | | update | groupId, title?, color?, collapsed? | Change group properties | | move | groupId, index | Reorder a group | | ungroup | tabIds | Remove tabs from their groups | | delete | groupId | Dissolve a group (tabs remain open) |

Colors: grey, blue, red, yellow, green, pink, purple, cyan, orange

HTTP REST Bridge

For environments that can't use MCP directly (e.g., sandboxed VMs), an HTTP server exposes all tools as REST endpoints:

npx @shawnowen/comet-mcp --http
# Or if installed locally: npm run http
# Starts on http://localhost:3456

See COWORK-BRIDGE.md for full endpoint documentation.

How It Works

Claude Code  →  MCP Server  →  CDP  →  Comet Browser  →  Perplexity AI
   (reasoning)     (bridge)                              (web browsing)

Direct mode: Claude sends DOM actions (comet_interact, comet_navigate) → CDP executes them instantly on the active page.

AI mode: Claude sends high-level goals (comet_ask) → Comet/Perplexity figures out the clicks, scrolls, and searches → results flow back.

Sidecar mode: Claude asks about the current page (comet_ask with sidecar: true) → Perplexity Assistant sees and interacts with the active tab → results flow back.

Requirements

• Node.js 18+
• Perplexity Comet Browser
• Claude Code (or any MCP client)
• Supported platforms: macOS, Windows, WSL2

Windows & WSL Support

Native Windows

Works out of the box. Comet MCP auto-detects Windows and launches Comet from its default install location.

WSL2 (Windows Subsystem for Linux)

WSL2 requires mirrored networking to connect to Comet running on Windows:

1. Enable mirrored networking (one-time setup):

   # Create/edit %USERPROFILE%\.wslconfig (Windows side)
   [wsl2]
   networkingMode=mirrored

2. Restart WSL:

   wsl --shutdown
   # Then reopen your WSL terminal

3. That's it! Comet MCP auto-detects WSL and uses PowerShell to communicate with Windows.

If mirrored networking isn't available, you'll see a helpful error message with setup instructions.

Custom Comet Path

If Comet is installed in a non-standard location:

{
  "mcpServers": {
    "comet-bridge": {
      "command": "npx",
      "args": ["-y", "@shawnowen/comet-mcp"],
      "env": {
        "COMET_PATH": "/path/to/your/Comet"
      }
    }
  }
}

Troubleshooting

"Cannot connect to Comet"

• macOS: Ensure Comet is installed at /Applications/Comet.app
• Windows: Comet should be in %LOCALAPPDATA%\Perplexity\Comet\Application\
• Check if port 9222 is available

"WSL cannot connect to Windows localhost"

• Enable mirrored networking (see WSL section above)
• Or run Claude Code from Windows PowerShell instead of WSL

"Tools not showing in Claude"

• Restart Claude Code after config changes

License

MIT

Report Issues · Contribute