0xHumban/perplexity-mcp

perplexity-mcp

A Perplexity AI MCP (Model Context Protocol) server implementation that enables AI assistants to search the web and get real-time information through Perplexity's Sonar models.

Motivation

This project was created to utilize the $5 credits from Perplexity's Pro plan (free for students: perplexity link), providing an easy way to access web search capabilities through MCP-compatible AI assistants.

Features

• 🌐 Web search capabilities through Perplexity AI
• 🔍 Multiple Sonar models support (sonar, sonar-pro, sonar-deep-research, sonar-reasoning, sonar-reasoning-pro)
• 🚀 Easy integration with VS Code and other MCP clients
• 📚 Citation support for sources

Prerequisites

• Python 3.12 or higher
• UV package manager
• Perplexity API key (Get one here)

Installation

Method 1: No Installation Required (Recommended)

You can run perplexity-mcp directly without any installation using uv tool run. Just install UV and configure VS Code (see Configuration section below) - uv will handle everything automatically!

# Install UV package manager first
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# or
brew install uv  # macOS with Homebrew

Method 2: Development Install

For development or to contribute:

1. Install UV Package Manager

# macOS (Homebrew)
brew install uv

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux (Direct)
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the repository

git clone https://github.com/0xHumban/perplexity-mcp.git
cd perplexity-mcp

3. Install dependencies

uv sync

Configuration

For VS Code

NOTE: To add it globaly: Create / Update the gloabl config file: ~/.config/Code/User/mcp.json

If you used Method 1 (No Installation - Recommended):

Create or edit .vscode/mcp.json in your workspace:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "API Key for Perplexity AI",
      "password": true
    }
  ],
  "servers": {
    "perplexity-mcp": {
      "command": "uv",
      "args": [
        "tool", "run", "--from",
        "git+https://github.com/0xHumban/perplexity-mcp.git",
        "perplexity-mcp"
      ],
      "env": {
        "PERPLEXITY_API_KEY": "${input:perplexity-key}"
      }
    }
  }
}

This method runs the tool directly from GitHub without any prior installation!

If you used Method 2 (Development Install):

Create or edit .vscode/mcp.json in your workspace:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "API Key for Perplexity AI",
      "password": true
    }
  ],
  "servers": {
    "perplexity-mcp": {
      "command": "uv",
      "args": [
        "run",
        "perplexity-mcp"
      ],
      "cwd": "/path/to/perplexity-mcp",
      "env": {
        "PERPLEXITY_API_KEY": "${input:perplexity-key}"
      }
    }
  }
}

Replace /path/to/perplexity-mcp with the actual path to your cloned repository.

Then:

1. Reload VS Code window
2. Enter your Perplexity API key when prompted

For other MCP clients

Set the environment variable:

export PERPLEXITY_API_KEY="your-api-key-here"

Then run:

uv run perplexity-mcp

Available Features

The Perplexity MCP server provides four main tools to interact with the Perplexity AI API:

1. ask_perplexity - Standard Search

Main tool for performing web searches via Perplexity AI.

How it works:

• Sends a query to Perplexity AI to get up-to-date information from the web
• Returns a formatted response with cited sources
• Uses the default model (sonar) unless otherwise specified

Use cases:

• Search for recent or real-time information
• Get answers based on multiple web sources
• Verify facts or current statistics

Example:

#ask_perplexity
What are the latest AI developments in October 2024?

2. ask_perplexity_exact_response - Unmodified Response

Returns the exact response from Perplexity AI without any modification or reformatting.

How it works:

• Similar to ask_perplexity but preserves Perplexity's original response
• No additional processing is applied
• Ideal when you want Perplexity's raw answer

Use cases:

• When you want to see exactly what Perplexity responded
• To avoid any interpretation or reformatting by the assistant
• Get citations and sources exactly as Perplexity provides them

Example:

#ask_perplexity_exact_response
Search for the latest tech news in France

3. ask_perplexity_for_instructions - Instructions Mode

Designed to obtain detailed and executable instructions on a complex topic.

How it works:

• Uses a special pedagogical preprompt that guides Perplexity to provide structured instructions
• Ideal for learning or understanding technical concepts
• Returns detailed steps, code examples, and clear explanations

Use cases:

• Learn a new concept or technology
• Get a step-by-step guide to accomplish a task
• Understand complex topics with practical examples
• Generate example code with detailed explanations

Example:

#ask_perplexity_for_instructions
Create a REST API server in Go for my books database

4. ask_perplexity_to_learn - Learning Mode

Pedagogical tool specially designed for learning complex topics.

How it works:

• Uses an advanced pedagogical preprompt that structures the response to facilitate learning
• Breaks down concepts into logical steps
• Provides analogies, concrete examples, and comprehension checks
• Uses the reasoning model by default for more in-depth explanations

Response structure:

1. Simple overview of the concept
2. Breakdown into logical steps (3-7 steps)
3. For each step: simple explanation + concrete example + commented code
4. Checkpoints to verify understanding
5. Summary of key points and tips to go further

Use cases:

• Learning complex computer science concepts (algorithms, data structures, etc.)
• Understanding mathematical principles
• Studying new technologies or frameworks
• Self-directed learning on technical topics

Example:

#ask_perplexity_to_learn
Teach me arithmetic coding step by step with code examples in Go

Available Sonar Models

All tools support the following models:

• sonar (default for ask_perplexity and ask_perplexity_exact_response)

  • Fast, general-purpose search
  • Good balance between speed and quality
  • Ideal for most queries

• sonar-pro

  • Enhanced accuracy and depth
  • More sources and analysis
  • Recommended for important searches

• sonar-deep-research

  • Comprehensive and thorough research
  • Complete analysis of multiple sources
  • For serious research projects

• sonar-reasoning (default for ask_perplexity_for_instructions and ask_perplexity_to_learn)

  • Advanced reasoning capabilities
  • Better for complex explanations
  • Ideal for learning and instructions

• sonar-reasoning-pro

  • Premium reasoning with extended context
  • Most powerful for complex tasks
  • Best understanding and explanation

Development

Project Structure

perplexity-mcp/
├── perplexity_mcp/
│   ├── __init__.py
│   ├── server.py       # Main MCP server implementation
│   └── cli.py
├── pyproject.toml      # Project configuration
├── uv.lock            # Dependency lock file
└── README.md

License

See file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.