{
  "markdown": "# Perplexity Comet MCP\n\n[![npm version](https://img.shields.io/npm/v/perplexity-comet-mcp.svg)](https://www.npmjs.com/package/perplexity-comet-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/perplexity-comet-mcp.svg)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)\n[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20WSL-lightgrey.svg)]()\n\nA 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.\n\n---\n\n## Why Perplexity Comet MCP?\n\n| Approach | Limitation |\n|----------|------------|\n| **Search APIs** | Static text, no interaction, no login support |\n| **Browser Automation** | Single-agent model overwhelms context, fragments focus |\n| **Perplexity Comet MCP** | Claude codes while Comet handles browsing autonomously |\n\nThis 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.\n\n---\n\n## Features\n\n### Core Capabilities\n\n- **Autonomous Web Browsing** - Comet navigates, clicks, types, and extracts data while Claude focuses on coding\n- **Deep Research Mode** - Leverage Perplexity's research capabilities for comprehensive analysis\n- **Login Wall Handling** - Access authenticated content through real browser sessions\n- **Dynamic Content** - Full JavaScript rendering and interaction support\n\n### Enhanced Features (New in This Fork)\n\n| Feature | Description |\n|---------|-------------|\n| **Windows/WSL Support** | Full compatibility with Windows and WSL environments |\n| **Tab Management** | Track, switch, and close browser tabs with protection |\n| **Smart Completion** | Detect response completion without fixed timeouts |\n| **Auto-Reconnect** | Exponential backoff recovery from connection drops |\n| **One-Shot Reliability** | Pre-operation health checks for consistent execution |\n| **Agentic Auto-Trigger** | Automatically triggers browser actions from natural prompts |\n\n---\n\n## Comparison with Original\n\n| Capability | Original | Enhanced |\n|------------|----------|----------|\n| Platform Support | macOS | Windows, WSL, macOS |\n| Available Tools | 6 | 8 (+comet_tabs, +comet_upload) |\n| Completion Detection | Fixed timeout | Stability-based |\n| Connection Recovery | None | Auto-reconnect with backoff |\n| Tab Management | None | Full registry and control |\n| Health Monitoring | None | Cached health checks |\n| Last Tab Protection | None | Prevents browser crash |\n\n---\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18 or higher\n- [Perplexity Comet Browser](https://www.perplexity.ai/comet) installed\n- Claude Code or compatible MCP client\n\n### Install via npm\n\n```bash\nnpm install -g perplexity-comet-mcp\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/RapierCraft/perplexity-comet-mcp.git\ncd perplexity-comet-mcp\nnpm install\nnpm run build\n```\n\n### Configure Claude Code\n\nAdd to your Claude Code MCP settings (`~/.claude/settings.json` or VS Code settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"comet-bridge\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/perplexity-comet-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n**Windows Users:** Use the full Windows path:\n\n```json\n{\n  \"mcpServers\": {\n    \"comet-bridge\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\Users\\\\YourName\\\\perplexity-comet-mcp\\\\dist\\\\index.js\"]\n    }\n  }\n}\n```\n\n---\n\n## Tools Reference\n\n### comet_connect\n\nEstablish connection to Comet browser. Auto-launches if not running.\n\n```\nParameters: None\nReturns: Connection status message\n```\n\n**Example:**\n```\n> comet_connect\nComet started with debug port 9223\nConnected to Perplexity (cleaned 2 old tabs)\n```\n\n---\n\n### comet_ask\n\nSend a prompt to Comet and wait for the complete response. Automatically triggers agentic browsing for URLs and action-oriented requests.\n\n```\nParameters:\n  - prompt (required): Question or task for Comet\n  - newChat (optional): Start fresh conversation (default: false)\n  - timeout (optional): Max wait time in ms (default: 120000)\n\nReturns: Complete response text\n```\n\n**Examples:**\n\n```\n# Simple research query\n> comet_ask \"What are the latest features in Python 3.12?\"\n\n# Agentic browsing (auto-triggered)\n> comet_ask \"Go to github.com/trending and list top Python repos\"\n\n# Site-specific data extraction\n> comet_ask \"Check the price of iPhone 15 on amazon.com\"\n```\n\n---\n\n### comet_poll\n\nCheck status and progress of ongoing tasks. Returns the response if completed.\n\n```\nParameters: None\nReturns: Status (IDLE/WORKING/COMPLETED), steps taken, or final response\n```\n\n**Example:**\n```\n> comet_poll\nStatus: WORKING\nBrowsing: https://github.com/trending\nCurrent: Scrolling page\n\nSteps:\n  - Preparing to assist you\n  - Navigating to github.com\n  - Clicking on Trending\n  - Scrolling page\n```\n\n---\n\n### comet_stop\n\nHalt the current agentic task if it goes off track.\n\n```\nParameters: None\nReturns: Confirmation message\n```\n\n---\n\n### comet_screenshot\n\nCapture a screenshot of the current browser view.\n\n```\nParameters: None\nReturns: PNG image data\n```\n\n---\n\n### comet_tabs\n\nView and manage browser tabs. Essential for multi-tab workflows.\n\n```\nParameters:\n  - action (optional): \"list\" (default), \"switch\", or \"close\"\n  - domain (optional): Domain to match (e.g., \"github.com\")\n  - tabId (optional): Specific tab ID\n\nReturns: Tab listing or action confirmation\n```\n\n**Examples:**\n\n```\n# List all external tabs\n> comet_tabs\n2 browsing tab(s) open:\n  - AGENT-BROWSING: github.com [ACTIVE]\n    URL: https://github.com/trending\n  - AGENT-BROWSING: stackoverflow.com\n    URL: https://stackoverflow.com/questions\n\n# Switch to a tab\n> comet_tabs action=\"switch\" domain=\"stackoverflow.com\"\nSwitched to stackoverflow.com (https://stackoverflow.com/questions)\n\n# Close a tab (protected if last tab)\n> comet_tabs action=\"close\" domain=\"github.com\"\nClosed github.com\n```\n\n**Tab Protection:**\n- Cannot close the last external browsing tab (prevents Comet crash)\n- Internal tabs (chrome://, Perplexity UI) are automatically filtered\n\n---\n\n### comet_mode\n\nSwitch Perplexity search modes for different use cases.\n\n```\nParameters:\n  - mode (optional): \"search\", \"research\", \"labs\", or \"learn\"\n\nReturns: Current mode or confirmation of switch\n```\n\n| Mode | Use Case |\n|------|----------|\n| search | Quick web searches |\n| research | Deep, comprehensive analysis |\n| labs | Data analytics and visualization |\n| learn | Educational explanations |\n\n---\n\n### comet_upload\n\nUpload files to file input elements on web pages. Essential for posting images to social media, attaching files to forms, or uploading documents.\n\n```\nParameters:\n  - filePath (required): Absolute path to the file to upload\n  - selector (optional): CSS selector for specific file input\n  - checkOnly (optional): If true, only checks what file inputs exist\n\nReturns: Success message or error with available inputs\n```\n\n**Examples:**\n\n```\n# Upload an image to the first file input found\n> comet_upload filePath=\"/home/user/screenshot.png\"\nFile uploaded successfully: /home/user/screenshot.png\n\n# Check what file inputs exist on the page\n> comet_upload filePath=\"dummy\" checkOnly=true\nFound 2 file input(s) on the page:\n  1. #image-upload\n  2. input[name=\"attachment\"]\n\n# Upload to a specific input\n> comet_upload filePath=\"/home/user/doc.pdf\" selector=\"#attachment-input\"\nFile uploaded successfully: /home/user/doc.pdf\n```\n\n**Workflow for posting images:**\n1. Navigate to the post creation page (e.g., Reddit, Twitter)\n2. Use `comet_upload checkOnly=true` to find file inputs\n3. Use `comet_upload filePath=\"...\" selector=\"...\"` to attach the file\n4. Continue with form submission\n\n---\n\n## Architecture\n\n```\n┌─────────────────┐     MCP Protocol      ┌──────────────────┐\n│   Claude Code   │ ◄──────────────────► │  Perplexity      │\n│   (Your IDE)    │                       │  Comet MCP       │\n└─────────────────┘                       └────────┬─────────┘\n                                                   │\n                                          Chrome DevTools\n                                            Protocol\n                                                   │\n                                          ┌────────▼─────────┐\n                                          │  Comet Browser   │\n                                          │  (Perplexity)    │\n                                          └──────────────────┘\n                                                   │\n                                          ┌────────▼─────────┐\n                                          │   External       │\n                                          │   Websites       │\n                                          └──────────────────┘\n```\n\n### Key Components\n\n| Component | Purpose |\n|-----------|---------|\n| `index.ts` | MCP server and tool handlers |\n| `cdp-client.ts` | Chrome DevTools Protocol client with reconnection logic |\n| `comet-ai.ts` | Perplexity interaction, prompt submission, response extraction |\n| `types.ts` | TypeScript interfaces for tabs, state, and CDP types |\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `COMET_PATH` | Custom path to Comet executable | Auto-detected |\n| `COMET_PORT` | CDP debugging port | 9223 |\n\n### Custom Comet Path\n\n```bash\n# Windows\nset COMET_PATH=C:\\Custom\\Path\\comet.exe\n\n# macOS/Linux\nexport COMET_PATH=/custom/path/to/Comet.app/Contents/MacOS/Comet\n```\n\n---\n\n## Troubleshooting\n\n### Connection Issues\n\n**Problem:** `Error: Failed to list targets: ECONNREFUSED`\n\n**Solutions:**\n1. Ensure Comet browser is installed\n2. Close any existing Comet instances\n3. Run `comet_connect` to auto-start with correct flags\n\n---\n\n**Problem:** `WebSocket connection closed` during long tasks\n\n**Solution:** This version handles reconnection automatically. If persistent, increase timeout:\n\n```\ncomet_ask prompt=\"...\" timeout=180000\n```\n\n---\n\n### Windows-Specific Issues\n\n**Problem:** `ECONNRESET` errors on Windows\n\n**Solution:** This version includes PowerShell-based fetch workarounds. Ensure:\n1. PowerShell is available in PATH\n2. No firewall blocking localhost:9223\n\n---\n\n**Problem:** Comet not found on Windows\n\n**Solution:** Set custom path:\n```bash\nset COMET_PATH=%LOCALAPPDATA%\\Perplexity\\Comet\\Application\\comet.exe\n```\n\n---\n\n### WSL-Specific Issues\n\n**Problem:** `WSL cannot connect to Windows localhost:9223`\n\n**Explanation:** WSL2 uses a separate network namespace by default. The MCP uses Chrome DevTools Protocol (CDP) which requires WebSocket connections to Windows localhost.\n\n**Solution:** Enable WSL mirrored networking:\n\n1. Create or edit `%USERPROFILE%\\.wslconfig` (e.g., `C:\\Users\\YourName\\.wslconfig`):\n```ini\n[wsl2]\nnetworkingMode=mirrored\n```\n\n2. Restart WSL:\n```powershell\nwsl --shutdown\n```\n\n3. Open a new WSL terminal and try again.\n\n**Alternative:** Run Claude Code from Windows PowerShell instead of WSL.\n\n---\n\n**Problem:** `UNC paths are not supported` warnings\n\n**Explanation:** This is a benign warning from PowerShell when launched from WSL. The MCP handles this automatically.\n\n---\n\n### Tab Management Issues\n\n**Problem:** `Cannot close - this is the only browsing tab`\n\n**Explanation:** This is intentional protection. Comet requires at least one external tab. Open another tab first, then close the unwanted one.\n\n---\n\n## Development\n\n### Build from Source\n\n```bash\ngit clone https://github.com/RapierCraft/perplexity-comet-mcp.git\ncd perplexity-comet-mcp\nnpm install\nnpm run build\n```\n\n### Run in Development\n\n```bash\nnpm run dev\n```\n\n### Run Tests\n\n```bash\nnpm test\n```\n\n### Project Structure\n\n```\nperplexity-comet-mcp/\n├── src/\n│   ├── index.ts        # MCP server entry point\n│   ├── cdp-client.ts   # CDP connection management\n│   ├── comet-ai.ts     # AI interaction logic\n│   └── types.ts        # TypeScript definitions\n├── dist/               # Compiled JavaScript\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request.\n\n### Development Guidelines\n\n1. Maintain TypeScript strict mode compliance\n2. Add tests for new features\n3. Update documentation for API changes\n4. Follow existing code style\n\n---\n\n## Attribution\n\nThis project is an enhanced fork of [comet-mcp](https://github.com/hanzili/comet-mcp) by [hanzili](https://github.com/hanzili).\n\n### Key Enhancements by RapierCraft\n\n- Windows and WSL platform support\n- Tab management system (comet_tabs tool)\n- Smart completion detection\n- Auto-reconnect with exponential backoff\n- Health check caching\n- Agentic prompt auto-transformation\n- Last tab protection\n- Internal tab filtering\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## Links\n\n- [Perplexity Comet Browser](https://www.perplexity.ai/comet)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Claude Code](https://claude.ai/code)\n- [Original comet-mcp](https://github.com/hanzili/comet-mcp)\n\n---\n\nBuilt with precision by [RapierCraft](https://github.com/RapierCraft)\n",
  "bytes": 13435,
  "sha": "7136289c216852e7559201501b2fc6473d368c949d707728dc58530a1e607d7e",
  "repo_slug": "rapiercraft/perplexity-comet-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rapiercraft_perplexity_comet_m_f000292e/readme"
}