Perplexity MCP Server

# 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](https://docs.astral.sh/uv/) - [Perplexity API key](https://www.perplexity.ai/settings/api) - [Claude Desktop](https://claude.ai/download) ### Installation 1. **Clone the repository** ```bash git clone <repository-url> cd Perplexity_MCP ``` 2. **Install dependencies** ```bash uv sync ``` 3. **Set up environment** ```bash echo "PERPLEXITY_API_KEY=your_api_key_here" > .env ``` 4. **Test the installation** ```bash uv run python tests/tests.py small ``` ### Claude Desktop Integration 1. **Find your UV path** ```bash which uv # Example output: /Users/username/.local/bin/uv ``` 2. **Configure Claude Desktop** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: ```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 | 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: ```json { "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: ```bash # 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** ```bash uv sync --all-groups ``` 2. **Run the MCP server locally** (for debugging) ```bash uv run python server.py ``` 3. **Check code quality** ```bash uv run ruff check . uv run black . ``` ## Configuration ### Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `PERPLEXITY_API_KEY` | Yes | Your Perplexity API key from [settings page](https://www.perplexity.ai/settings/api) | ### Tool Configuration The tools are configured in `config.py`: ```python 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](https://www.perplexity.ai/settings/api) **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: ```bash uv run python server.py # Check stderr output for detailed logging information ``` ### Test Individual Components ```bash # 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](LICENSE) - see LICENSE file for details. ## Acknowledgments - [Perplexity AI](https://www.perplexity.ai/) for the powerful search-enhanced language models - [Anthropic](https://www.anthropic.com/) for Claude and the MCP protocol - [FastMCP](https://github.com/jlowin/fastmcp) for the excellent MCP framework ## Support - For API issues: [Perplexity Support](https://www.perplexity.ai/support) - For MCP protocol questions: [MCP Documentation](https://modelcontextprotocol.io/) - For Claude Desktop issues: [Claude Support](https://support.anthropic.com/) --- **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.