Perplexity MCP Server

MCP server that exposes Perplexity AI's search capabilities to Claude, enabling seamless research integration during conversations.

🚧 Development Status

Current Version: v0.1.0-alpha (In Active Development)

✅ Completed

• Project foundation and security setup
• Configuration management with API key validation
• Perplexity API client with retry logic and error handling
• MCP server implementation with FastMCP
• Comprehensive testing suite
• Security validation and sanitisation

🔮 Planned (Future Phases)

• Perplexity Spaces integration
• Memory and context management
• Thread summarisation across Spaces
• Cross-platform data synthesis
• Document generation from multi-source data

Note: This project is in early development. The API and features may change.

---

Installation

Prerequisites

• Python 3.10 or higher
• Perplexity API key (Get one here)
• Claude Desktop or Claude Code with MCP support

Step-by-Step Setup

1. Clone the repository

   git clone https://github.com/yourusername/claude-perplexity-mcp-server.git
   cd claude-perplexity-mcp-server

2. Create a virtual environment (recommended)

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment variables

   # Copy the example file
   cp .env.example .env
   
   # Edit .env and add your Perplexity API key
   # PERPLEXITY_API_KEY=pplx-your-actual-api-key-here

5. Verify configuration

   python -c "from config import get_config; print('Configuration loaded successfully')"

6. Test the server (optional)

   python server.py

Configuration

All configuration is managed through environment variables in the .env file. See .env.example for the template.

Environment Variables

Variable	Required	Default	Description
PERPLEXITY_API_KEY	Yes	-	Your Perplexity API key (starts with pplx-)
DEFAULT_MODEL	No	sonar-pro	Default Perplexity model to use
CACHE_ENABLED	No	false	Enable caching (future feature)
LOG_LEVEL	No	INFO	Logging level: DEBUG, INFO, WARNING, ERROR

Model Options

• sonar - Standard model
• sonar-pro - Enhanced model with better reasoning (recommended)

Search Focus Options

• web - General web search (default)
• academic - Academic and research sources
• sec - Security-focused sources

Recency Filters

• hour - Last hour
• day - Last day
• week - Last week
• month - Last month
• year - Last year

Usage

Setting Up Claude Desktop

1. Locate Claude Desktop configuration

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add MCP server configuration

   {
     "mcpServers": {
       "perplexity-search": {
         "command": "python",
         "args": ["C:/path/to/claude-perplexity-mcp-server/server.py"],
         "env": {
           "PERPLEXITY_API_KEY": "pplx-your-key-here"
         }
       }
     }
   }

   Note: For Windows, use forward slashes or escaped backslashes in the path:

   "args": ["C:\\Users\\YourName\\path\\to\\server.py"]

3. Restart Claude Desktop

4. Verify the tool is available

   • The perplexity_search tool should appear in Claude's available tools
   • You can ask Claude: "What tools do you have available?"

Using the Tool

Simply ask Claude to search for information:

"Search Perplexity for the latest developments in quantum computing"

Or be more specific:

"Use perplexity_search to find recent news about Python 3.12 features"

Tool Parameters

Claude can use these parameters when calling the tool:

• query (required): Your search question
• model (optional): Override default model (sonar or sonar-pro)
• search_focus (optional): web, academic, or sec
• recency (optional): hour, day, week, month, or year

Example Queries

• "What are the latest AI developments?"
• "Search for recent research on climate change solutions"
• "Find current information about the Python programming language"

Known Limitations

Citation Display Issues

Current Status: Citations are included in the tool response but may not display correctly in Claude Desktop's UI.

• Raw JSON: Citations appear correctly in the raw tool response JSON
• Text Display: Citation markers and links may not render in Claude Desktop's text output
• Workaround: Check the raw tool response in Claude Desktop's developer tools or JSON view

We are actively working on resolving this limitation. This is a known issue with how Claude Desktop handles MCP tool responses and citation formatting.

Other Limitations

• Rate limits apply based on your Perplexity API tier
• Network timeouts may occur with slow connections (automatic retry with backoff)
• Very long queries (>10,000 characters) are rejected for safety

Troubleshooting

Server Won't Start

Problem: ModuleNotFoundError: No module named 'mcp'

Solution:

pip install -r requirements.txt

Problem: ValueError: PERPLEXITY_API_KEY not found

Solution:

• Ensure .env file exists in the project root
• Verify PERPLEXITY_API_KEY is set in .env
• Check that the API key starts with pplx-

Tool Not Appearing in Claude Desktop

Problem: Tool doesn't show up in Claude Desktop

Solutions:

1. Verify the path in claude_desktop_config.json is correct
2. Ensure Python is in your system PATH
3. Check that server.py is executable
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors

API Errors

Problem: API authentication failed

Solution:

• Verify your API key is correct in .env
• Ensure the API key hasn't expired
• Check your Perplexity account for API usage limits

Problem: Rate limit exceeded

Solution:

• Wait a few moments and try again
• Check your Perplexity API tier and rate limits
• Consider upgrading your Perplexity plan if needed

Network Issues

Problem: Request timed out

Solution:

• Check your internet connection
• Verify Perplexity API is accessible from your network
• Try again (automatic retry with exponential backoff)

Configuration Issues

Problem: Invalid model or parameter errors

Solution:

• Check .env.example for valid options
• Verify DEFAULT_MODEL is set to sonar or sonar-pro
• Ensure search_focus values are: web, academic, or sec
• Ensure recency values are: hour, day, week, month, or year

Security

Best Practices

• Never commit .env files - They contain sensitive API keys
• Use environment variables - All secrets are loaded from .env
• Sanitised logging - API keys are never logged in full
• URL validation - Citations are validated to prevent malicious URLs

Security Checklist Before Committing

Run this before every commit:

• .env is in .gitignore and NOT staged
• No API keys in code, comments, or documentation
• .env.example contains only placeholder values
• Error messages don't expose secrets
• Logs are sanitised
• All secrets use environment variables

Quick check: git diff --cached and search for pplx-

See SECURITY.md for detailed security policies and responsible disclosure guidelines.

Development

Running Tests

python test_phase5.py

Project Structure

claude-perplexity-mcp-server/
├── .env.example          # Configuration template
├── .gitignore           # Git ignore rules
├── README.md            # This file
├── SECURITY.md          # Security policy
├── requirements.txt     # Python dependencies
├── config.py           # Configuration management
├── perplexity_client.py # Perplexity API client
├── server.py           # MCP server implementation
└── test_phase5.py      # Test suite

Code Quality

• Type hints throughout
• Comprehensive error handling
• Security-first design
• PEP 8 compliant
• Docstrings for all public functions

Contributing

Contributions are welcome! Please ensure:

1. Code follows existing style and patterns
2. All tests pass
3. Security checklist is followed
4. Documentation is updated
5. Type hints are included

License

Apache 2.0 License - see LICENSE file for details.

Support

For issues, questions, or contributions:

• Security issues: See SECURITY.md
• Bug reports: Open an issue on GitHub
• Feature requests: Open an issue with the enhancement label

Acknowledgements

• Built with FastMCP - High-level MCP SDK
• Powered by Perplexity AI - AI-powered search
• Designed for Claude Desktop - Anthropic's AI assistant