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

• Python 3.11+
• UV package manager
• Perplexity API key
• Claude Desktop

Installation

1. Clone the repository

   git clone <repository-url>
   cd Perplexity_MCP
   

2. Install dependencies

   uv sync
   

3. Set up environment

   echo "PERPLEXITY_API_KEY=your_api_key_here" > .env
   

4. Test the installation

   uv run python tests/tests.py small
   

Claude Desktop Integration

1. Find your UV path

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

2. 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"
         ]
       }
     }
   }
   

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

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

1. Install development dependencies

   uv sync --all-groups
   

2. Run the MCP server locally (for debugging)

   uv run python server.py
   

3. Check code quality

   uv run ruff check .
   uv run black .
   

Configuration

Environment Variables

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

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test thoroughly
4. Update documentation as needed
5. 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.