Perplexity Comet MCP

Perplexity Comet MCP

A production-grade MCP (Model Context Protocol) server that bridges Claude Code with Perplexity's Comet browser for autonomous web browsing, research, and multi-tab workflow management.

---

Why Perplexity Comet MCP?

This is a significantly enhanced fork of hanzili/comet-mcp with Windows support, smart completion detection, robust connection handling, and full tab management.

---

Features

Core Capabilities

• Autonomous Web Browsing - Comet navigates, clicks, types, and extracts data while Claude focuses on coding
• Deep Research Mode - Leverage Perplexity's research capabilities for comprehensive analysis
• Login Wall Handling - Access authenticated content through real browser sessions
• Dynamic Content - Full JavaScript rendering and interaction support

Enhanced Features (New in This Fork)

---

Comparison with Original

---

Installation

Prerequisites

• Node.js 18 or higher
• Perplexity Comet Browser installed
• Claude Code or compatible MCP client

Install via npm

npm install -g perplexity-comet-mcp

Install from Source

git clone https://github.com/RapierCraft/perplexity-comet-mcp.git

cd perplexity-comet-mcp npm install npm run build

Configure Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json or VS Code settings):

{

"mcpServers": { "comet-bridge": { "command": "node", "args": ["/path/to/perplexity-comet-mcp/dist/index.js"] } } }

Windows Users: Use the full Windows path:

{

"mcpServers": { "comet-bridge": { "command": "node", "args": ["C:\\Users\\YourName\\perplexity-comet-mcp\\dist\\index.js"] } } }

---

Tools Reference

comet_connect

Establish connection to Comet browser. Auto-launches if not running.

Parameters: None

Returns: Connection status message

Example:

> comet_connect

Comet started with debug port 9223 Connected to Perplexity (cleaned 2 old tabs)

---

comet_ask

Send a prompt to Comet and wait for the complete response. Automatically triggers agentic browsing for URLs and action-oriented requests.

Parameters:

• prompt (required): Question or task for Comet
• newChat (optional): Start fresh conversation (default: false)
• timeout (optional): Max wait time in ms (default: 120000)

Returns: Complete response text

Examples:

# Simple research query

comet_ask "What are the latest features in Python 3.12?"

Agentic browsing (auto-triggered)

comet_ask "Go to github.com/trending and list top Python repos"

Site-specific data extraction

comet_ask "Check the price of iPhone 15 on amazon.com"

---

comet_poll

Check status and progress of ongoing tasks. Returns the response if completed.

Parameters: None

Returns: Status (IDLE/WORKING/COMPLETED), steps taken, or final response

Example:

> comet_poll

Status: WORKING Browsing: https://github.com/trending Current: Scrolling page

Steps:

• Preparing to assist you
• Navigating to github.com
• Clicking on Trending
• Scrolling page

---

comet_stop

Halt the current agentic task if it goes off track.

Parameters: None

Returns: Confirmation message

---

comet_screenshot

Capture a screenshot of the current browser view.

Parameters: None

Returns: PNG image data

---

comet_tabs

View and manage browser tabs. Essential for multi-tab workflows.

Parameters:

• action (optional): "list" (default), "switch", or "close"
• domain (optional): Domain to match (e.g., "github.com")
• tabId (optional): Specific tab ID

Returns: Tab listing or action confirmation

Examples:

# List all external tabs

comet_tabs

2 browsing tab(s) open:

• AGENT-BROWSING: github.com [ACTIVE] URL: https://github.com/trending
• AGENT-BROWSING: stackoverflow.com URL: https://stackoverflow.com/questions

Switch to a tab

comet_tabs action="switch" domain="stackoverflow.com"

Switched to stackoverflow.com (https://stackoverflow.com/questions)

Close a tab (protected if last tab)

comet_tabs action="close" domain="github.com"

Closed github.com

Tab Protection:

• Cannot close the last external browsing tab (prevents Comet crash)
• Internal tabs (chrome://, Perplexity UI) are automatically filtered

---

comet_mode

Switch Perplexity search modes for different use cases.

Parameters:

• mode (optional): "search", "research", "labs", or "learn"

Returns: Current mode or confirmation of switch

---

comet_upload

Upload files to file input elements on web pages. Essential for posting images to social media, attaching files to forms, or uploading documents.

Parameters:

• filePath (required): Absolute path to the file to upload
• selector (optional): CSS selector for specific file input
• checkOnly (optional): If true, only checks what file inputs exist

Returns: Success message or error with available inputs

Examples:

# Upload an image to the first file input found

comet_upload filePath="/home/user/screenshot.png"

File uploaded successfully: /home/user/screenshot.png

Check what file inputs exist on the page

comet_upload filePath="dummy" checkOnly=true

Found 2 file input(s) on the page:

1. #image-upload
2. input[name="attachment"]

Upload to a specific input

comet_upload filePath="/home/user/doc.pdf" selector="#attachment-input"

File uploaded successfully: /home/user/doc.pdf

Workflow for posting images:

1. Navigate to the post creation page (e.g., Reddit, Twitter)
2. Use comet_upload checkOnly=true to find file inputs
3. Use comet_upload filePath="..." selector="..." to attach the file
4. Continue with form submission

---

Architecture

┌─────────────────┐     MCP Protocol      ┌──────────────────┐

│ Claude Code │ ◄──────────────────► │ Perplexity │ │ (Your IDE) │ │ Comet MCP │ └─────────────────┘ └────────┬─────────┘ │ Chrome DevTools Protocol │ ┌────────▼─────────┐ │ Comet Browser │ │ (Perplexity) │ └──────────────────┘ │ ┌────────▼─────────┐ │ External │ │ Websites │ └──────────────────┘

Key Components

---

Configuration

Environment Variables

Custom Comet Path

# Windows

set COMET_PATH=C:\Custom\Path\comet.exe

macOS/Linux

export COMET_PATH=/custom/path/to/Comet.app/Contents/MacOS/Comet

---

Troubleshooting

Connection Issues

Problem: Error: Failed to list targets: ECONNREFUSED

Solutions:

1. Ensure Comet browser is installed
2. Close any existing Comet instances
3. Run comet_connect to auto-start with correct flags

---

Problem: WebSocket connection closed during long tasks

Solution: This version handles reconnection automatically. If persistent, increase timeout:

comet_ask prompt="..." timeout=180000

---

Windows-Specific Issues

Problem: ECONNRESET errors on Windows

Solution: This version includes PowerShell-based fetch workarounds. Ensure:

1. PowerShell is available in PATH
2. No firewall blocking localhost:9223

---

Problem: Comet not found on Windows

Solution: Set custom path:

set COMET_PATH=%LOCALAPPDATA%\Perplexity\Comet\Application\comet.exe

---

WSL-Specific Issues

Problem: WSL cannot connect to Windows localhost:9223

Explanation: WSL2 uses a separate network namespace by default. The MCP uses Chrome DevTools Protocol (CDP) which requires WebSocket connections to Windows localhost.

Solution: Enable WSL mirrored networking:

1. Create or edit %USERPROFILE%\.wslconfig (e.g., C:\Users\YourName\.wslconfig):

[wsl2]

networkingMode=mirrored

1. Restart WSL:

wsl --shutdown

1. Open a new WSL terminal and try again.

Alternative: Run Claude Code from Windows PowerShell instead of WSL.

---

Problem: UNC paths are not supported warnings

Explanation: This is a benign warning from PowerShell when launched from WSL. The MCP handles this automatically.

---

Tab Management Issues

Problem: Cannot close - this is the only browsing tab

Explanation: This is intentional protection. Comet requires at least one external tab. Open another tab first, then close the unwanted one.

---

Development

Build from Source

git clone https://github.com/RapierCraft/perplexity-comet-mcp.git

cd perplexity-comet-mcp npm install npm run build

Run in Development

npm run dev

Run Tests

npm test

Project Structure

perplexity-comet-mcp/

├──