perplexity-mcp
Provides tools for web search and real-time information retrieval using Perplexity AI's Sonar models, supporting multiple search and reasoning modes with citation support.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@perplexity-mcp What are the latest breakthroughs in AI?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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 HomebrewMethod 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 | sh2. Clone the repository
git clone https://github.com/0xHumban/perplexity-mcp.git
cd perplexity-mcp3. Install dependencies
uv syncConfiguration
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:
Reload VS Code window
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-mcpAvailable 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_perplexitybut preserves Perplexity's original responseNo 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 France3. 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 database4. 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:
Simple overview of the concept
Breakdown into logical steps (3-7 steps)
For each step: simple explanation + concrete example + commented code
Checkpoints to verify understanding
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 GoAvailable 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-proEnhanced accuracy and depth
More sources and analysis
Recommended for important searches
sonar-deep-researchComprehensive 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-proPremium 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.mdLicense
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 toolsask_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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Enable AI assistants to perform web searches using Perplexity's Sonar Pro.
Real-time web search, reasoning, and research through Perplexity's API
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Web search API and MCP server for developers building AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides 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.475,070 npm2,639MIT
- FlicenseBqualityDmaintenanceEnables AI assistants to perform real-time web and academic searches using Perplexity's Sonar API.2-
- AlicenseBqualityDmaintenanceEnables 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.1MIT
- AlicenseAqualityBmaintenanceConnects 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.1200 npm6MIT