A
securityA
licenseA
qualityA server facilitating web search functionality by utilizing Perplexity AI's API, designed to integrate with the Claude desktop client for enhanced search queries.
Last updated -
252
MIT License
Integrates Perplexity AI's search-enhanced language models, providing three tools with progressive complexity for different search and research needs: perplexity_small for quick factual queries, perplexity_medium for technical explanations, and perplexity_large for comprehensive research.
Perplexity MCP Server
A Model Context Protocol (MCP) server that integrates Perplexity AI's search-enhanced language models with Claude Desktop, providing three tools with progressive complexity for different use cases.
Features
🔍 Three Complexity Levels
perplexity_small: Fast queries with sonar-pro modelperplexity_medium: Enhanced reasoning with sonar-reasoning-properplexity_large: Deep research with sonar-deep-research
🚀 Optimized for Development
Clean responses (thinking tokens automatically removed)
Comprehensive error handling
Detailed logging for debugging
Built with FastMCP for reliability
🔧 Modern Python Stack
UV for fast dependency management
HTTPX for modern HTTP client capabilities
Type hints throughout codebase
Comprehensive testing suite
Quick Start
Prerequisites
Installation
Clone the repository
git clone <repository-url> cd Perplexity_MCPInstall dependencies
uv syncSet up environment
echo "PERPLEXITY_API_KEY=your_api_key_here" > .envTest the installation
uv run python tests/tests.py small
Claude Desktop Integration
Find your UV path
which uv # Example output: /Users/username/.local/bin/uvConfigure Claude Desktop
Edit
~/Library/Application Support/Claude/claude_desktop_config.json:{ "mcpServers": { "perplexity-mcp": { "command": "/Users/username/.local/bin/uv", "args": [ "--directory", "/path/to/your/Perplexity_MCP", "run", "python", "server.py" ] } } }Restart Claude Desktop
Completely quit and restart Claude Desktop to load the new MCP server.
Usage
In Claude Desktop
Once configured, you can use these tools in your conversations:
Quick factual queries:
Use perplexity_small to find: "What is the latest Python version?"
Technical analysis:
Use perplexity_medium to explain: "Compare REST vs GraphQL performance characteristics"
Deep research:
Use perplexity_large to research: "Comprehensive analysis of quantum computing trends in 2024"
Tool Specifications
Tool | Model | Use Case | Response Time | Features |
| sonar-pro | Quick facts, basic queries | ~3-10 seconds | Fast, reliable |
| sonar-reasoning-pro | Technical explanations | ~10-30 seconds | Enhanced reasoning |
| sonar-deep-research | Comprehensive research | ~5-30 minutes | Deep analysis, high quality |
Response Format
All tools return clean, structured responses:
{
"content": "The AI response with thinking tokens removed",
"citations": ["https://source1.com", "https://source2.com"]
}
Development
Project Structure
Perplexity_MCP/
├── server.py # FastMCP server with 3 tools
├── client.py # Perplexity API wrapper
├── config.py # Configuration and tool settings
├── __init__.py # Package exports
├── pyproject.toml # UV project configuration
├── tests/
│ ├── tests.py # Test script for individual tools
│ └── test_logs/ # Test results and logs
└── Notes/
├── explanations.md # Technical deep-dives
└── questions.txt # Development questions
Running Tests
Test individual tools to validate API integration:
# Test each tool independently
uv run python tests/tests.py small # Test sonar-pro model
uv run python tests/tests.py medium # Test sonar-reasoning-pro
uv run python tests/tests.py large # Test sonar-deep-research (long runtime)
# Results saved to tests/test_logs/ with detailed response analysis
Development Setup
Install development dependencies
uv sync --all-groupsRun the MCP server locally (for debugging)
uv run python server.pyCheck code quality
uv run ruff check . uv run black .
Configuration
Environment Variables
Variable | Required | Description |
| Yes | Your Perplexity API key from |
Tool Configuration
The tools are configured in config.py:
TOOL_CONFIGS = {
"small": {
"model": "sonar-pro"
},
"medium": {
"model": "sonar-reasoning-pro",
"reasoning_effort": "medium",
"web_search_options": {"search_context_size": "medium"}
},
"large": {
"model": "sonar-deep-research",
"reasoning_effort": "high",
"web_search_options": {"search_context_size": "high"}
}
}
Troubleshooting
Common Issues
Import Errors
ModuleNotFoundError: No module named 'client'
Ensure you're running from the project root directory
Check that UV is using the correct virtual environment
API Key Issues
Error: PERPLEXITY_API_KEY environment variable is required
Verify your
.envfile exists and contains the API keyCheck that the API key is valid on Perplexity's settings page
Claude Desktop Connection Issues
Verify the UV path in your configuration:
which uvEnsure the project directory path is absolute and correct
Check Claude Desktop logs for specific error messages
Restart Claude Desktop completely after configuration changes
Long Response Times
perplexity_largecan take 10-30 minutes for complex queriesUse
perplexity_smallorperplexity_mediumfor faster responsesConsider the complexity of your query when choosing tools
Debug Mode
Enable verbose logging by running the server directly:
uv run python server.py
# Check stderr output for detailed logging information
Test Individual Components
# Test API connection
uv run python -c "from client import PerplexityClient; print('✅ Client OK')"
# Test configuration
uv run python -c "from config import get_api_key; print('✅ API Key OK')"
# Test server startup
timeout 10s uv run python server.py || echo "Server started successfully"
Contributing
Fork the repository
Create a feature branch:
git checkout -b feature-nameMake your changes and test thoroughly
Update documentation as needed
Submit a pull request
Development Guidelines
Follow existing code style (Black formatting, type hints)
Add tests for new functionality
Update
CLAUDE.mdfor any architectural changesTest with all three Perplexity models
Ensure MCP protocol compliance (clean stdout)
Architecture
Key Design Decisions
Class-based client: Singleton pattern for efficient resource management
Thinking token removal: Automatic filtering of
<think>...</think>sectionsSimplified responses: Only content and citations for clean integration
Error isolation: No exceptions propagated to MCP layer
Logging strategy: All debug output to stderr for MCP compliance
Dependencies
mcp>=1.11.0- MCP Python SDK with FastMCPpython-dotenv>=1.1.1- Environment variable managementhttpx>=0.28.1- Modern HTTP client with timeout handling
License
MIT License - see LICENSE file for details.
Acknowledgments
Perplexity AI for the powerful search-enhanced language models
Anthropic for Claude and the MCP protocol
FastMCP for the excellent MCP framework
Support
For API issues: Perplexity Support
For MCP protocol questions: MCP Documentation
For Claude Desktop issues: Claude Support
Note: This MCP server is currently optimized for local development and personal use. Future versions may include PyPI distribution options for easier installation and sharing.
Integrates Perplexity AI's search-enhanced language models with Claude Desktop, providing three tools with different complexity levels for quick fact-checking, technical analysis, and deep research.
Related MCP Servers
- AsecurityAlicenseAqualityEnables intelligent code analysis and debugging through the Perplexity AI's API, offering detailed error analysis, pattern detection, and comprehensive solutions, with integration support for the Claude desktop client.Last updated -47411MIT License
- AsecurityAlicenseAqualityA custom MCP tool that integrates Perplexity AI's API with Claude Desktop, allowing Claude to perform web-based research and provide answers with citations.Last updated -14MIT License
- -securityAlicense-qualityA custom Model Context Protocol implementation that integrates Perplexity AI with Claude Desktop, allowing users to access Perplexity's AI models for both single questions and multi-turn conversations.Last updated -47412ISC License