Perplexity MCP

🚀 Perplexity MCP Server

A Model Context Protocol (MCP) server integrating Perplexity AI's search - enhanced language models with Claude Desktop. It offers three tools of increasing complexity to meet diverse use cases.

✨ Features

🔍 Three Complexity Levels

• perplexity_small: Conduct fast queries using the sonar - pro model.
• perplexity_medium: Perform enhanced reasoning with the sonar - reasoning - pro model.
• perplexity_large: Undertake deep research with the sonar - deep - research model.

🚀 Optimized for Development

• Provide clean responses by automatically removing thinking tokens.
• Implement comprehensive error handling.
• Offer detailed logging for debugging purposes.
• Be built with FastMCP for high reliability.

🔧 Modern Python Stack

• Use UV for fast dependency management.
• Employ HTTPX for modern HTTP client capabilities.
• Include type hints throughout the codebase.
• Have a 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 Examples

Basic Usage

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

📚 Documentation

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"

🔧 Technical Details

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.

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

💡 Usage Tip

This MCP server is currently optimized for local development and personal use. Future versions may include PyPI distribution options for easier installation and sharing.