Perplexity Comet MCP

![Platform]()

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

$3

- 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

$3

| 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

$3

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

$3

``bash
npm install -g perplexity-comet-mcp
`

$3

`bash
git clone https://github.com/RapierCraft/perplexity-comet-mcp.git
cd perplexity-comet-mcp
npm install
npm run build
`

$3

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

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

Windows Users: Use the full Windows path:

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

---

Tools Reference

$3

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)
`

---

$3

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"
`

---

$3

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
`

---

$3

Halt the current agentic task if it goes off track.

`
Parameters: None
Returns: Confirmation message
`

---

$3

Capture a screenshot of the current browser view.

`
Parameters: None
Returns: PNG image data
`

---

$3

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

---

$3

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 |

---

$3

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 │
└──────────────────┘
`

$3

| 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

$3

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

$3

`bash


Windows

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

macOS/Linux

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

---

Troubleshooting

$3

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
`

---

$3

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:
`bash
set COMET_PATH=%LOCALAPPDATA%\Perplexity\Comet\Application\comet.exe
`

---

$3

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):
`ini
[wsl2]
networkingMode=mirrored
`

2. Restart WSL:
`powershell
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.

---

$3

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

$3

`bash
git clone https://github.com/RapierCraft/perplexity-comet-mcp.git
cd perplexity-comet-mcp
npm install
npm run build
`

$3

`bash
npm run dev
`

$3

`bash
npm test
`

$3

`
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.

$3

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.

$3

- 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