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?

| Approach | Limitation | |----------|------------| | Search APIs | Static text, no interaction, no login support | | Browser Automation | Single-agent model overwhelms context, fragments focus | | Perplexity Comet MCP | Claude codes while Comet handles browsing autonomously |

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)

| Feature | Description | |---------|-------------| | Windows/WSL Support | Full compatibility with Windows and WSL environments | | Tab Management | Track, switch, and close browser tabs with protection | | Smart Completion | Detect response completion without fixed timeouts | | Auto-Reconnect | Exponential backoff recovery from connection drops | | One-Shot Reliability | Pre-operation health checks for consistent execution | | Agentic Auto-Trigger | Automatically triggers browser actions from natural prompts |

Comparison with Original

| Capability | Original | Enhanced | |------------|----------|----------| | Platform Support | macOS | Windows, WSL, macOS | | Available Tools | 6 | 8 (+comet_tabs, +comet_upload) | | Completion Detection | Fixed timeout | Stability-based | | Connection Recovery | None | Auto-reconnect with backoff | | Tab Management | None | Full registry and control | | Health Monitoring | None | Cached health checks | | Last Tab Protection | None | Prevents browser crash |

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

| Mode | Use Case | |------|----------| | search | Quick web searches | | research | Deep, comprehensive analysis | | labs | Data analytics and visualization | | learn | Educational explanations |

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

| Component | Purpose | |-----------|---------| | index.ts | MCP server and tool handlers | | cdp-client.ts | Chrome DevTools Protocol client with reconnection logic | | comet-ai.ts | Perplexity interaction, prompt submission, response extraction | | types.ts | TypeScript interfaces for tabs, state, and CDP types |

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | COMET_PATH | Custom path to Comet executable | Auto-detected | | COMET_PORT | CDP debugging port | 9223 |

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

2. Restart WSL:

wsl --shutdown

3. 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/
├── src/
│   ├── index.ts        # MCP server entry point
│   ├── cdp-client.ts   # CDP connection management
│   ├── comet-ai.ts     # AI interaction logic
│   └── types.ts        # TypeScript definitions
├── dist/               # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting a pull request.

Development Guidelines

1. Maintain TypeScript strict mode compliance
2. Add tests for new features
3. Update documentation for API changes
4. Follow existing code style

Attribution

This project is an enhanced fork of comet-mcp by hanzili.

Key Enhancements by RapierCraft

• Windows and WSL platform support
• Tab management system (comet_tabs tool)
• Smart completion detection
• Auto-reconnect with exponential backoff
• Health check caching
• Agentic prompt auto-transformation
• Last tab protection
• Internal tab filtering

License

MIT License - see LICENSE for details.

Links

• Perplexity Comet Browser
• Model Context Protocol
• Claude Code
• Original comet-mcp

Built with precision by RapierCraft