# Perplexity Web MCP Bridge

[![NPM Version](https://img.shields.io/npm/v/perplexity-web-mcp-bridge)](https://www.npmjs.com/package/perplexity-web-mcp-bridge)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub Issues](https://img.shields.io/github/issues/sukarth/perplexity-web-mcp-bridge)](https://github.com/sukarth/perplexity-web-mcp-bridge/issues)

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

```bash
# 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](https://github.com/sukarth/perplexity-web-mcp-extension).

## ✨ 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)
```bash
npx perplexity-web-mcp-bridge
```

#### Option 2: Global installation
```bash
npm install -g perplexity-web-mcp-bridge
perplexity-web-mcp-bridge
```

#### Option 3: Local development
```bash
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):
```bash
npm install -g @sukarth/bg-tm
```
Then, start the server:

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

#### **Stopping the server**
First list all running processes to find the correct process name or ID:
```bash
bg-tm list
```
Then, stop the server using its name:
```bash
bg-tm stop <name>
```

Please check the [BG-TM documentation](https://github.com/Sukarth/bg-tm#readme) for more information.

For using pm2 for running the server in the background, please refer to the [pm2 documentation](https://pm2.keymetrics.io/docs/usage/quick-start/). 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](https://github.com/sukarth/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`:

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

```bash
# 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**:
   ```bash
   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:
   ```bash
   git clone https://github.com/sukarth/perplexity-web-mcp-bridge.git
   cd perplexity-web-mcp-bridge
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Run in development mode:
   ```bash
   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](./md-files/ARCHITECTURE.md).

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](./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:
```bash
npx perplexity-web-mcp-bridge --dev
```

## 📝 Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.

## 🔒 Security

For security concerns, please see [SECURITY.md](./SECURITY.md).

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

## 🔗 Related Projects

- [Perplexity Web MCP Extension](https://github.com/sukarth/perplexity-web-mcp-extension) - The companion browser extension
- [MCP Servers Collection](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations

## 🙏 Acknowledgments

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the fantastic protocol
- [Perplexity AI](https://perplexity.ai/) for the amazing AI models and search interface
- The open source community for MCP server implementations

## 💖 Support

If this project helps or saves you time, consider supporting my work, as it keeps projects like this free, open source, and maintained:

[![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-%E2%9D%A4-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Sukarth)
[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?logo=kofi&logoColor=white)](https://ko-fi.com/sukarth)
[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-☕-FFDD00?logoColor=black)](https://buymeacoffee.com/sukarth)

Can't donate? Starring the repo ⭐, reporting bugs, and sharing the project help just as much!

---

Made with ❤️ by [Sukarth](https://github.com/sukarth)