io.github.RapierCraft/perplexity-comet-mcp
Bridge Claude Code with Perplexity Comet for autonomous browsing and tab management
Open source Open in the app JSON README (API)
About
Bridge Claude Code with Perplexity Comet for autonomous browsing and tab management
Details
- Kind
- MCP servers
- Topic
- Web search, scraping & browser
- Publisher
- rapiercraft
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.5.0
- Stars
- 48
- Forks
- 18
- Last push
- 2026-06-22T05:37:23Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:11
- Updated
- 2026-08-29 03:02:11
- Origin id
io.github.RapierCraft/perplexity-comet-mcp
README
# Perplexity Comet MCP
[](https://www.npmjs.com/package/perplexity-comet-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[]()
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](https://github.com/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](https://www.perplexity.ai/comet) installed
- Claude Code or compatible MCP client
### Install via npm
```bash
npm install -g perplexity-comet-mcp
```
### Install from Source
```bash
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):
```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
### 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
```bash
# 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:
```bash
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`):
```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.
---
### 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
```bash
git clone https://github.com/RapierCraft/perplexity-comet-mcp.git
cd perplexity-comet-mcp
npm install
npm run build
```
### Run in Development
```bash
npm run dev
```
### Run Tests
```bash
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](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](https://github.com/hanzili/comet-mcp) by [hanzili](https://github.com/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](LICENSE) for details.
---
## Links
- [Perplexity Comet Browser](https://www.perplexity.ai/comet)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Code](https://claude.ai/code)
- [Original comet-mcp](https://github.com/hanzili/comet-mcp)
---
Built with precision by [RapierCraft](https://github.com/RapierCraft)