Skip to main content
Glama
perplexity-mcp

perplexity-mcp

by 0xHumban

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.

Related MCP server: Perplexity Web-Search MCP

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

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

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 LICENSE 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.

Available Tools

5 tools
ask_perplexityA
Send a prompt to Perplexity and return the response.
Sonar models have internet access and can perform searches.

Use this for: research, current events, comparisons, finding information online.

Examples of good prompts:
- "What are the latest developments in quantum computing in 2025?"
- "Compare Python vs Rust for web development"
- "Explain the recent changes in EU privacy laws"
- "Find the best practices for React Server Components"

If the user wants to execute or learn complex tasks, use the reasoning model (sonar-reasoning)
If the user wants development work requiring real-time documentation lookup, research-intensive coding, use the reasoning model (sonar-reasoning).
But by default, use the research model (sonar).

Args:
    prompt: The prompt/question to send
    model: Sonar model (sonar, sonar-pro, sonar-deep-research, 
           sonar-reasoning, sonar-reasoning-pro)

Inputs: prompt (required), model. Returns: result

ask_perplexity_exact_responseA
Send a prompt to Perplexity and return the exact response without 
changing anything (no additional metadata or suggestions).

Use this when you need the raw, unmodified output from Perplexity.

Examples of good prompts:
- "Give me the exact documentation for FastAPI's dependency injection"
- "What does the official Next.js docs say about App Router?"
- "Show me the raw API response format for OpenAI's latest models"

If the user wants to execute or learn complex tasks, use the reasoning model (sonar-reasoning)
If the user wants development work requiring real-time documentation lookup, research-intensive coding, use the reasoning model (sonar-reasoning).
But by default, use the research model (sonar).

Sonar models have internet access and can perform searches.

Args:
    prompt: The prompt/question to send
    model: Sonar model (sonar, sonar-pro, sonar-deep-research, 
           sonar-reasoning, sonar-reasoning-pro)

Inputs: prompt (required), model. Returns: result

ask_perplexity_for_instructionsA
Send a prompt to Perplexity and get step-by-step instructions that 
Copilot can execute in agent mode.

This tool is optimized for tasks that require multiple steps or actions.
The response will be formatted as executable instructions for the AI agent.

Examples of good prompts:
- "How do I set up a Python FastAPI project with Docker?"
- "Create a React app with TypeScript and Tailwind CSS"
- "Set up CI/CD pipeline for a Node.js application"
- "Configure a PostgreSQL database with Redis caching"

Sonar models have internet access and can perform searches.

Args:
    prompt: The prompt/question to send
    model: Sonar model (sonar, sonar-pro, sonar-deep-research, 
           sonar-reasoning, sonar-reasoning-pro)

Inputs: prompt (required), model. Returns: result

ask_perplexity_to_learnA
Learn complex concepts with pedagogical explanations, examples, and analogies.

This tool uses a teaching-optimized approach with:
- Simple overviews and context
- Step-by-step breakdowns
- Concrete examples and analogies
- Code snippets when relevant
- Clear summaries and next steps

Examples of good prompts:
- "Explain how async/await works in Python"
- "Teach me about Docker containers and why they're useful"
- "What are React hooks and how do I use them?"
- "Explain database indexing with practical examples"
- "How does JWT authentication work?"

Sonar models have internet access and can perform searches.

Args:
    prompt: The prompt/question to send
    model: Sonar model (sonar, sonar-pro, sonar-deep-research, 
           sonar-reasoning, sonar-reasoning-pro)

Inputs: prompt (required), model. Returns: result

get_examplesA
Get examples of prompts and usage patterns for this Perplexity MCP server.

This tool helps you discover what you can do with this server and provides
concrete examples of effective prompts for each tool.

Returns:
    Detailed examples and usage guide for all available tools

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation4/5

    The four 'ask_perplexity_*' tools are differentiated by response style (general, exact, instructions, learning) with clear descriptions. The 'get_examples' tool is distinct. Some overlap between instructions and learning could cause minor ambiguity, but overall well-differentiated.

    Naming Consistency4/5

    All primary tools follow a consistent 'ask_perplexity_<purpose>' pattern. 'get_examples' uses a different verb-noun structure, but as a utility tool, this deviation is minor and acceptable.

    Tool Count5/5

    With 5 tools, the server is well-scoped for its purpose of querying Perplexity in different modes. Each tool earns its place without being excessive or insufficient.

    Completeness5/5

    The tool set covers a comprehensive range of use cases: general research, exact responses, step-by-step instructions, pedagogical learning, and an examples guide. No obvious gaps for the intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Provides AI assistants with real-time web search, reasoning, and research capabilities through Perplexity's Sonar models and Search API. Supports quick searches, deep research, advanced reasoning, and direct web search with ranked results.
      4
      75,070 npm
      2,639
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables web search using Perplexity AI's API, allowing users to search the web with optional recency filters and integration with Claude, Cursor, and other MCP clients.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects AI assistants to Perplexity AI's search API, enabling natural language web search with fine-grained control over recency, citations, images, and model parameters directly from MCP clients like Claude.
      1
      200 npm
      6
      MIT