Skip to main content
Glama

MCP Perplexity Pro

by cfdude
npmGitHub
TypeScript
4
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP Perplexity Pro

A comprehensive Model Context Protocol (MCP) server for the Perplexity API, featuring intelligent model selection, conversation management, and project-aware storage.

npm version License: MIT TypeScript

✨ Features

  • 🧠 Intelligent Model Selection: Automatically chooses the optimal Perplexity model based on query analysis

  • 💬 Conversation Management: Stateful chat sessions with full conversation history

  • 🔍 Comprehensive Search: Access to all Perplexity models (sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research)

  • 📊 Async Operations: Support for long-running research tasks

  • 🗂️ Project-Aware Storage: Conversations and reports stored in your project directory

  • 🔒 Thread-Safe: Concurrent access with file locking

  • 🐳 Docker Ready: Full Docker and Docker Compose support

  • 📈 Production Ready: Comprehensive error handling, logging, and monitoring

  • 🧪 Well Tested: Extensive unit and integration test coverage

🚀 Quick Start

Prerequisites

Installation

npm install -g mcp-perplexity-pro

🚀 Deployment Options

1. NPX Deployment (stdio-npx)

The simplest way to use the MCP server with stdio transport:

For Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "perplexity": { "command": "npx", "args": ["mcp-perplexity-pro-stdio"], "env": { "PERPLEXITY_API_KEY": "your-api-key-here" } } } }

For Claude Code (.mcp.json):

{ "mcpServers": { "perplexity": { "command": "npx", "args": ["mcp-perplexity-pro-stdio"], "env": { "PERPLEXITY_API_KEY": "your-api-key-here" } } } }

2. Docker Deployment (stdio-docker)

Run the MCP server in a Docker container with stdio transport:

Using Docker Compose:

# Set your API key export PERPLEXITY_API_KEY="your-api-key-here" # Start the stdio service docker-compose --profile stdio up -d mcp-perplexity-pro-stdio

For Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "perplexity": { "command": "docker", "args": ["exec", "-i", "mcp-perplexity-pro-stdio", "node", "/app/dist/stdio-server.js"], "env": { "PERPLEXITY_API_KEY": "your-api-key-here" } } } }

Direct Docker Run:

docker run -it --rm \ -e PERPLEXITY_API_KEY="your-api-key-here" \ -v "$(pwd)/data:/app/data" \ mcp-perplexity-pro:stdio

3. HTTP Transport (Legacy)

For Claude Code (.mcp.json):

{ "mcpServers": { "perplexity": { "command": "node", "args": ["dist/launcher.js", "--http-port=8124"], "env": { "PERPLEXITY_API_KEY": "your-api-key-here" } } } }

For Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "perplexity": { "command": "node", "args": ["dist/launcher.js", "--http-port=8125"], "env": { "PERPLEXITY_API_KEY": "your-api-key-here" } } } }

Default Ports:

  • Claude Code: 8124 (default when no port specified)

  • Claude Desktop: 8125 (recommended)

Environment Variables:

  • PERPLEXITY_API_KEY (required): Your Perplexity API key

  • DEFAULT_MODEL (optional): Default model (default: sonar-reasoning-pro)

  • PROJECT_ROOT (optional): Project root directory for storage

  • STORAGE_PATH (optional): Storage subdirectory (default: .perplexity)

The launcher automatically:

  • Detects if a build is needed and rebuilds if necessary

  • Starts HTTP server with streamable transport

  • No manual build or start commands required

📋 Available Tools

Query Tools

ask_perplexity

Ask questions with intelligent model selection based on query type.

Parameters:

  • query (required): Your question or prompt

  • model (optional): Specific model to use

  • temperature (optional): Response creativity (0.0-2.0)

  • max_tokens (optional): Maximum response length

Example:

Ask Perplexity: "What are the latest developments in quantum computing?"

research_perplexity

Conduct comprehensive research with detailed reports saved to your project.

Parameters:

  • query (required): Research topic or question

  • model (optional): Defaults to sonar-deep-research

  • save_report (optional): Save detailed report to project

Example:

Research: "Market analysis of renewable energy trends in 2024"

Chat Tools

chat_perplexity

Start or continue conversations with full context.

Parameters:

  • message (required): Your message

  • chat_id (optional): Continue existing conversation

  • title (optional): Title for new conversation

  • model (optional): Model selection

Example:

Chat: "Hello, I'd like to discuss AI ethics" (title: "AI Ethics Discussion")

list_chats_perplexity

List all conversations in your project.

read_chat_perplexity

Retrieve full conversation history.

Parameters:

  • chat_id (required): Conversation ID

Async Tools

async_perplexity

Create long-running research jobs for complex queries.

Parameters:

  • query (required): Research question

  • model (optional): Defaults to sonar-deep-research

check_async_perplexity

Check status of async research job.

Parameters:

  • job_id (required): Job identifier

list_async_jobs

List all async jobs in your project.

Utility Tools

storage_stats_perplexity

Get storage statistics and usage information.

model_info_perplexity

Get information about available models and their capabilities.

🧠 Intelligent Model Selection

The server automatically selects the optimal model based on query analysis:

Query Type

Selected Model

Use Case

Research requests

sonar-deep-research

"I need comprehensive research on..."

Real-time queries

sonar-pro

"What's the current price of...", "Latest news..."

Complex reasoning

sonar-reasoning-pro

"Analyze the implications of...", "Compare and contrast..."

Simple questions

sonar-reasoning

General questions

Default

sonar-reasoning-pro

Fallback for all other queries

Model Capabilities

{ "sonar": { search: true, reasoning: false, realTime: false, research: false }, "sonar-pro": { search: true, reasoning: false, realTime: true, research: false }, "sonar-reasoning": { search: true, reasoning: true, realTime: false, research: false }, "sonar-reasoning-pro": { search: true, reasoning: true, realTime: true, research: false }, "sonar-deep-research": { search: true, reasoning: true, realTime: false, research: true } }

🗂️ Project-Aware Storage

All conversations and research reports are stored in your project directory:

your-project/ ├── .perplexity/ │ ├── chats/ │ │ ├── chat-uuid-1.json │ │ └── chat-uuid-2.json │ ├── reports/ │ │ ├── research-report-1.json │ │ └── research-report-2.json │ └── async-jobs/ │ ├── job-uuid-1.json │ └── job-uuid-2.json

Storage Features

  • Thread-safe: File locking prevents concurrent access issues

  • Session-aware: Multiple sessions can work with the same project

  • Organized: Separate directories for different content types

  • Persistent: All data survives server restarts

  • Portable: Easy to backup, move, or version control

🐳 Docker Deployment

Development

# Clone repository git clone https://github.com/cfdude/mcp-perplexity-pro.git cd mcp-perplexity-pro # Start development environment docker-compose --profile dev up -d

Production

# Set environment variables export PROJECT_ROOT=/path/to/your/project # Start production environment docker-compose up -d

Custom Docker

FROM mcp-perplexity-pro:latest # Custom configuration COPY my-config.json /app/config.json # Custom entrypoint CMD ["node", "dist/index.js", "--config", "config.json"]

⚙️ Configuration

Environment Variables

Variable

Description

Default

NODE_ENV

Environment mode

development

PERPLEXITY_API_KEY

Your API key

Required

PROJECT_ROOT

Project directory

Current directory

STORAGE_PATH

Storage subdirectory

.perplexity

DEFAULT_MODEL

Default model

sonar-reasoning-pro

SESSION_ID

Session identifier

Auto-generated

Advanced Configuration

{ "api_key": "your-key", "default_model": "sonar-reasoning-pro", "project_root": "/workspace", "storage_path": ".perplexity", "session_id": "unique-session", "request_timeout": 30000, "max_retries": 3, "rate_limit": { "requests_per_minute": 60, "concurrent_requests": 5 } }

🧪 Development

Setup

# Clone and install git clone https://github.com/cfdude/mcp-perplexity-pro.git cd mcp-perplexity-pro npm install # Development mode npm run dev # Run tests npm test npm run test:coverage # Linting and formatting npm run lint npm run format

Project Structure

src/ ├── index.ts # Main MCP server ├── types.ts # TypeScript definitions ├── models.ts # Model registry & selection ├── perplexity-api.ts # API client wrapper ├── storage.ts # Storage management └── tools/ ├── query.ts # Query tools ├── chat.ts # Chat tools └── async.ts # Async tools tests/ ├── models.test.ts # Model selection tests ├── storage.test.ts # Storage tests ├── perplexity-api.test.ts # API tests └── integration.test.ts # End-to-end tests

Testing

# Run all tests npm test # Watch mode npm run test:watch # Coverage report npm run test:coverage # Specific test file npm test -- models.test.ts

📊 API Usage Examples

Basic Query

// Simple question const result = await askPerplexity({ query: 'What is machine learning?', }); // With specific model const result = await askPerplexity({ query: 'Current Bitcoin price', model: 'sonar-pro', });

Conversation

// Start new conversation const chat = await chatPerplexity({ message: 'Hello!', title: 'General Discussion', }); // Continue conversation const response = await chatPerplexity({ chat_id: chat.id, message: 'Tell me about quantum computing', });

Research

// Comprehensive research const research = await researchPerplexity({ query: 'Impact of AI on healthcare industry', save_report: true, }); // Async research for complex topics const job = await asyncPerplexity({ query: 'Detailed analysis of climate change solutions', }); // Check job status const status = await checkAsync({ job_id: job.id, });

🔒 Security

API Key Management

  • Store API keys securely using environment variables

  • Never commit API keys to version control

  • Rotate keys regularly

  • Use different keys for different environments

Network Security

  • HTTPS in production

  • Rate limiting implemented

  • Input validation and sanitization

  • Error handling without information leakage

Container Security

  • Non-root user execution

  • Minimal base images

  • Regular security updates

  • Vulnerability scanning

📈 Monitoring

Health Checks

# Basic health check curl http://localhost:3000/health # Detailed status curl http://localhost:3000/status

Metrics

The server exposes Prometheus-compatible metrics:

  • Request count and duration

  • Error rates by endpoint

  • Storage usage statistics

  • Model usage distribution

Logging

Structured JSON logging with configurable levels:

{ "timestamp": "2024-08-20T19:00:00.000Z", "level": "info", "message": "Query processed successfully", "model": "sonar-reasoning-pro", "duration": 1250, "session_id": "session-123" }

🚨 Troubleshooting

Common Issues

API Key Errors

Error: Invalid API key Solution: Verify PERPLEXITY_API_KEY is set correctly

Storage Permission Errors

Error: EACCES: permission denied Solution: Ensure storage directory is writable

Model Selection Issues

Error: Model not available Solution: Check model name spelling and availability

Debug Mode

DEBUG=mcp-perplexity:* npm start

Support

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests for new functionality

  5. Ensure all tests pass

  6. Submit a pull request

Code Standards

  • TypeScript with strict mode

  • ESLint + Prettier formatting

  • 100% test coverage for new features

  • Conventional commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

📊 Project Stats

GitHub stars GitHub forks GitHub issues GitHub pull requests

Built with ❤️ for the MCP community

This server cannot be installed

-
security - not tested
-
license - not tested
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A comprehensive MCP server that provides intelligent access to Perplexity AI's search and reasoning models with automatic model selection, conversation management, and project-aware storage. Supports real-time search, deep research, chat sessions, and async operations for complex queries.

  1. ✨ Features
    1. 🚀 Quick Start
      1. Prerequisites
      2. Installation
    2. 🚀 Deployment Options
      1. 1. NPX Deployment (stdio-npx)
      2. 2. Docker Deployment (stdio-docker)
      3. 3. HTTP Transport (Legacy)
    3. 📋 Available Tools
      1. Query Tools
      2. Chat Tools
      3. Async Tools
      4. Utility Tools
    4. 🧠 Intelligent Model Selection
      1. Model Capabilities
    5. 🗂️ Project-Aware Storage
      1. Storage Features
    6. 🐳 Docker Deployment
      1. Development
      2. Production
      3. Custom Docker
    7. ⚙️ Configuration
      1. Environment Variables
      2. Advanced Configuration
    8. 🧪 Development
      1. Setup
      2. Project Structure
      3. Testing
    9. 📊 API Usage Examples
      1. Basic Query
      2. Conversation
      3. Research
    10. 🔒 Security
      1. API Key Management
      2. Network Security
      3. Container Security
    11. 📈 Monitoring
      1. Health Checks
      2. Metrics
      3. Logging
    12. 🚨 Troubleshooting
      1. Common Issues
      2. Debug Mode
      3. Support
    13. 🤝 Contributing
      1. Development Workflow
      2. Code Standards
    14. 📄 License
      1. 🙏 Acknowledgments
        1. 📊 Project Stats

          Related MCP Servers

          • Perplexity AI MCP Server

            mkusaka
            A
            security
            -
            license
            A
            quality
            An MCP server integrating Perplexity AI's API to offer advanced search capabilities with support for multiple models and result configuration.
            Last updated -
            531
            1
            MIT License

          • Perplexity AI MCP Server

            -
            security
            -
            license
            -
            quality
            This server provides access to the Perplexity AI API, enabling interaction through chatting, searching, and documentation retrieval within MCP-based systems.

          • Perplexity AI MCP Server

            rileyedwards77
            A
            security
            -
            license
            A
            quality
            Provides a standardized way to integrate Perplexity AI's features like chat, search, and documentation access into MCP-based systems.
            Last updated -
            1

          • Perplexity MCP Server

            RossH121
            A
            security
            -
            license
            A
            quality
            An MCP server that enables Claude to perform web searches using Perplexity's API with intelligent model selection based on query intent and support for domain and recency filtering.
            Last updated -
            3
            MIT License
            • Apple

          View all related MCP servers

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/cfdude/mcp-perplexity-pro'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server