Perplexity Web MCP Bridge

A bridge that enables Perplexity's web interface to use MCP (Model Context Protocol) tools and servers, allowing for seamless integration of local data sources, APIs, and custom tools directly into your Perplexity chat experience.

🚀 Quick Start

# Install and run the bridge
npx perplexity-web-mcp-bridge

# Or install globally
npm install -g perplexity-web-mcp-bridge
perplexity-web-mcp-bridge

Then install the companion browser extension from the Browser Extension Repository.

✨ Features

• Seamless Integration: Use MCP tools directly from Perplexity's chat interface
• Local Data Access: Connect to local databases, filesystems, and APIs
• Custom Tools: Extend Perplexity's capabilities with your own MCP servers
• Real-time Bridge: WebSocket-based communication for instant responses
• Easy Configuration: Simple JSON configuration for MCP server management
• Cross-Platform: Works on Windows, macOS, and Linux

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Perplexity    │    │     Bridge      │    │   MCP Servers   │
│  Web Interface  │◄──►│   (WebSocket)   │◄──►│  (GitHub, etc)  │
│  + Extension    │    │    CLI Tool     │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

The bridge consists of three main components:

1. CLI Tool (this repository): Runs a WebSocket server that connects to MCP servers
2. Browser Extension: Injects MCP capabilities into Perplexity's web interface
3. Configuration System: Manages MCP server connections and settings

📦 Installation & Usage

Prerequisites

• Node.js 18+
• npm or yarn
• Chrome/Chromium browser

CLI Tool Installation

Option 1: Run directly with npx (Recommended)

npx perplexity-web-mcp-bridge

Option 2: Global installation

npm install -g perplexity-web-mcp-bridge
perplexity-web-mcp-bridge

Option 3: Local development

git clone https://github.com/sukarth/perplexity-web-mcp-bridge.git
cd perplexity-web-mcp-bridge
npm install
npm start

Run as a Background Service

This CLI tool/server can also be run as a background service on Windows, macOS, and Linux using a another tool like BG-TM or PM2, so that the terminal window does not need to be kept open for the server to keep running.

Starting the server

First, install BG-TM (globally):

npm install -g @sukarth/bg-tm

Then, start the server:

bg-tm run "npx perplexity-web-mcp-bridge"

Stopping the server

First list all running processes to find the correct process name or ID:

bg-tm list

Then, stop the server using its name:

bg-tm stop <name>

Please check the BG-TM documentation for more information.

For using pm2 for running the server in the background, please refer to the pm2 documentation. Note that pm2 is not properly supported for Windows for this use case.

Browser Extension Installation

The browser extension is available in a separate repository: perplexity-web-mcp-extension

1. Download and install the extension from the repository
2. Enable it in Chrome
3. The extension will automatically connect to the bridge

⚙️ Configuration

Basic Configuration

Create a configuration file at ~/.perplexity-mcp/config.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    }
  }
}

Available MCP Servers

Popular MCP servers you can integrate:

• GitHub: @modelcontextprotocol/server-github - Repository management
• Filesystem: @modelcontextprotocol/server-filesystem - Local file operations
• PostgreSQL: @modelcontextprotocol/server-postgres - Database queries
• Brave Search: @modelcontextprotocol/server-brave-search - Web search
• SQLite: @modelcontextprotocol/server-sqlite - SQLite database access

Configuration Options

| Option | Description | Default | |----------|----------------------------|-----------------------------------| | port | WebSocket server port | 54319 | | config | Config file path | ~/.perplexity-mcp/config.json | | dev | Enable verbose logging | false |

Example Commands

# Start the bridge with default settings
npx perplexity-web-mcp-bridge

# Specify a custom port
npx perplexity-web-mcp-bridge --port 60000

# Use a custom config file
npx perplexity-web-mcp-bridge --config /path/to/config.json

# Enable verbose logging (dev mode)
npx perplexity-web-mcp-bridge --dev

# Combine options
npx perplexity-web-mcp-bridge --port 60000 --config /path/to/config.json --dev

🎯 Usage

1. Start the bridge:

   npx perplexity-web-mcp-bridge

2. Install the browser extension from the companion repository

3. Open Perplexity.ai in Chrome

4. Use MCP tools directly in your conversations:

   • "Search my GitHub repositories for React projects"
   • "What files are in my ~/Documents folder?"
   • "Query my PostgreSQL database for user statistics"

🏗️ Project Structure

perplexity-web-mcp-bridge/
├── bin/
│   └── cli.js              # Main CLI entry point
├── src/
│   ├── bridge.js           # WebSocket server & MCP management
│   └── config.js           # Configuration handling

├── CHANGELOG.md            # Version history
├── CONTRIBUTING.md         # Contribution guidelines
├── SECURITY.md             # Security policy

├── package.json
├── README.md
└── LICENSE

🛠️ Development

Local Development Setup

1. Clone the repository:

   git clone https://github.com/sukarth/perplexity-web-mcp-bridge.git
   cd perplexity-web-mcp-bridge

2. Install dependencies:

   npm install

3. Run in development mode:

   npm run dev

Available Scripts

• npm start - Start the bridge server
• npm run dev - Start with verbose logging
• npm test - Run tests (if available)

Project Architecture Deep Dive

For detailed architecture information, see ARCHITECTURE.md.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests if applicable
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

🐛 Troubleshooting

Common Issues

Bridge won't start

• Check if port 54319 is available
• Verify Node.js version (18+ required)
• Check configuration file syntax

MCP servers not connecting

• Verify MCP server packages are installed
• Check environment variables (API tokens, etc.)
• Review configuration file paths

Extension not working

• Ensure bridge is running
• Check browser console for errors
• Verify extension is enabled

Debug Mode

Run with verbose logging:

npx perplexity-web-mcp-bridge --dev

📝 Changelog

See CHANGELOG.md for version history.

🔒 Security

For security concerns, please see SECURITY.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Perplexity Web MCP Extension - The companion browser extension
• MCP Servers Collection - Official MCP server implementations

🙏 Acknowledgments

• Model Context Protocol (MCP) for the fantastic protocol
• Perplexity AI for the amazing AI models and search interface
• The open source community for MCP server implementations

Made with ❤️ by Sukarth