Provides comprehensive access to Perplexity AI's search and reasoning models, enabling intelligent query processing, conversation management, research tasks, and async operations with automatic model selection based on query analysis.
MCP Perplexity Pro
A comprehensive Model Context Protocol (MCP) server for the Perplexity API, featuring intelligent model selection, conversation management, and project-aware storage.
โจ Features
๐ง Intelligent Model Selection: Automatically chooses the optimal Perplexity model based on query analysis
๐ฌ Conversation Management: Stateful chat sessions with full conversation history
๐ Comprehensive Search: Access to all Perplexity models (sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research)
๐ Async Operations: Support for long-running research tasks
๐๏ธ Project-Aware Storage: Conversations and reports stored in your project directory
๐ Thread-Safe: Concurrent access with file locking
๐ณ Docker Ready: Full Docker and Docker Compose support
๐ Production Ready: Comprehensive error handling, logging, and monitoring
๐งช Well Tested: Extensive unit and integration test coverage
๐ Quick Start
Prerequisites
Node.js 20+
Perplexity API key (Get one here)
Installation
๐ Deployment Options
1. NPX Deployment (stdio-npx)
The simplest way to use the MCP server with stdio transport:
For Claude Desktop (claude_desktop_config.json
):
For Claude Code (.mcp.json
):
2. Docker Deployment (stdio-docker)
Run the MCP server in a Docker container with stdio transport:
Using Docker Compose:
For Claude Desktop (claude_desktop_config.json
):
Direct Docker Run:
3. HTTP Transport (Legacy)
For Claude Code (.mcp.json
):
For Claude Desktop (claude_desktop_config.json
):
Default Ports:
Claude Code: 8124 (default when no port specified)
Claude Desktop: 8125 (recommended)
Environment Variables:
PERPLEXITY_API_KEY
(required): Your Perplexity API keyDEFAULT_MODEL
(optional): Default model (default: sonar-reasoning-pro)PROJECT_ROOT
(optional): Project root directory for storageSTORAGE_PATH
(optional): Storage subdirectory (default: .perplexity)
The launcher automatically:
Detects if a build is needed and rebuilds if necessary
Starts HTTP server with streamable transport
No manual build or start commands required
๐ Available Tools
Query Tools
ask_perplexity
Ask questions with intelligent model selection based on query type.
Parameters:
query
(required): Your question or promptmodel
(optional): Specific model to usetemperature
(optional): Response creativity (0.0-2.0)max_tokens
(optional): Maximum response length
Example:
research_perplexity
Conduct comprehensive research with detailed reports saved to your project.
Parameters:
query
(required): Research topic or questionmodel
(optional): Defaults tosonar-deep-research
save_report
(optional): Save detailed report to project
Example:
Chat Tools
chat_perplexity
Start or continue conversations with full context.
Parameters:
message
(required): Your messagechat_id
(optional): Continue existing conversationtitle
(optional): Title for new conversationmodel
(optional): Model selection
Example:
list_chats_perplexity
List all conversations in your project.
read_chat_perplexity
Retrieve full conversation history.
Parameters:
chat_id
(required): Conversation ID
Async Tools
async_perplexity
Create long-running research jobs for complex queries.
Parameters:
query
(required): Research questionmodel
(optional): Defaults tosonar-deep-research
check_async_perplexity
Check status of async research job.
Parameters:
job_id
(required): Job identifier
list_async_jobs
List all async jobs in your project.
Utility Tools
storage_stats_perplexity
Get storage statistics and usage information.
model_info_perplexity
Get information about available models and their capabilities.
๐ง Intelligent Model Selection
The server automatically selects the optimal model based on query analysis:
Query Type | Selected Model | Use Case |
Research requests |
| "I need comprehensive research on..." |
Real-time queries |
| "What's the current price of...", "Latest news..." |
Complex reasoning |
| "Analyze the implications of...", "Compare and contrast..." |
Simple questions |
| General questions |
Default |
| Fallback for all other queries |
Model Capabilities
๐๏ธ Project-Aware Storage
All conversations and research reports are stored in your project directory:
Storage Features
Thread-safe: File locking prevents concurrent access issues
Session-aware: Multiple sessions can work with the same project
Organized: Separate directories for different content types
Persistent: All data survives server restarts
Portable: Easy to backup, move, or version control
๐ณ Docker Deployment
Development
Production
Custom Docker
โ๏ธ Configuration
Environment Variables
Variable | Description | Default |
| Environment mode |
|
| Your API key | Required |
| Project directory | Current directory |
| Storage subdirectory |
|
| Default model |
|
| Session identifier | Auto-generated |
Advanced Configuration
๐งช Development
Setup
Project Structure
Testing
๐ API Usage Examples
Basic Query
Conversation
Research
๐ Security
API Key Management
Store API keys securely using environment variables
Never commit API keys to version control
Rotate keys regularly
Use different keys for different environments
Network Security
HTTPS in production
Rate limiting implemented
Input validation and sanitization
Error handling without information leakage
Container Security
Non-root user execution
Minimal base images
Regular security updates
Vulnerability scanning
๐ Monitoring
Health Checks
Metrics
The server exposes Prometheus-compatible metrics:
Request count and duration
Error rates by endpoint
Storage usage statistics
Model usage distribution
Logging
Structured JSON logging with configurable levels:
๐จ Troubleshooting
Common Issues
API Key Errors
Storage Permission Errors
Model Selection Issues
Debug Mode
Support
๐ Documentation
๐ Issues
๐ฌ Discussions
๐ค Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Workflow
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request
Code Standards
TypeScript with strict mode
ESLint + Prettier formatting
100% test coverage for new features
Conventional commit messages
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Acknowledgments
Perplexity AI for providing the excellent API
Model Context Protocol for the MCP specification
Smithery for MCP development tools
The open-source community for inspiration and contributions
๐ Project Stats
Built with โค๏ธ for the MCP community
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A comprehensive MCP server that provides intelligent access to Perplexity AI's search and reasoning models with automatic model selection, conversation management, and project-aware storage. Supports real-time search, deep research, chat sessions, and async operations for complex queries.
- โจ Features
- ๐ Quick Start
- ๐ Deployment Options
- ๐ Available Tools
- ๐ง Intelligent Model Selection
- ๐๏ธ Project-Aware Storage
- ๐ณ Docker Deployment
- โ๏ธ Configuration
- ๐งช Development
- ๐ API Usage Examples
- ๐ Security
- ๐ Monitoring
- ๐จ Troubleshooting
- ๐ค Contributing
- ๐ License
- ๐ Acknowledgments
- ๐ Project Stats
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server integrating Perplexity AI's API to offer advanced search capabilities with support for multiple models and result configuration.Last updated -5311MIT License
- AsecurityFlicenseAqualityThis server provides access to the Perplexity AI API, enabling interaction through chatting, searching, and documentation retrieval within MCP-based systems.
- AsecurityFlicenseAqualityProvides a standardized way to integrate Perplexity AI's features like chat, search, and documentation access into MCP-based systems.Last updated -1
- AsecurityAlicenseAqualityAn MCP server that enables Claude to perform web searches using Perplexity's API with intelligent model selection based on query intent and support for domain and recency filtering.Last updated -3MIT License