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 model
perplexity_medium: Enhanced reasoning with sonar-reasoning-pro
perplexity_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_MCP

Install dependencies
```
uv sync
```

Set up environment

echo "PERPLEXITY_API_KEY=your_api_key_here" > .env

Test the installation
```
uv run python tests/tests.py small
```

Claude Desktop Integration

Find your UV path

which uv
# Example output: /Users/username/.local/bin/uv

Configure 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
`perplexity_small`	sonar-pro	Quick facts, basic queries	~3-10 seconds	Fast, reliable
`perplexity_medium`	sonar-reasoning-pro	Technical explanations	~10-30 seconds	Enhanced reasoning
`perplexity_large`	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-groups
```
Run the MCP server locally (for debugging)
```
uv run python server.py
```
Check code quality
```
uv run ruff check .
uv run black .
```

Configuration

Environment Variables

Variable	Required	Description
`PERPLEXITY_API_KEY`	Yes	Your Perplexity API key from settings page

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 .env file exists and contains the API key
Check that the API key is valid on Perplexity's settings page

Claude Desktop Connection Issues

Verify the UV path in your configuration: which uv
Ensure 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_large can take 10-30 minutes for complex queries
Use perplexity_small or perplexity_medium for faster responses
Consider 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-name
Make 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.md for any architectural changes
Test 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> sections
Simplified 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 FastMCP
python-dotenv>=1.1.1 - Environment variable management
httpx>=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.