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

Related MCP server: Perplexity MCP Server

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:

Technical analysis:

Deep research:

Tool Specifications

Response Format

All tools return clean, structured responses:

Development

Project Structure

Running Tests

Test individual tools to validate API integration:

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:

Troubleshooting

Common Issues

Import Errors

• Ensure you're running from the project root directory

• Check that UV is using the correct virtual environment

API Key Issues

• 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:

Test Individual Components

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.