MCP Perplexity Pro

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

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

• Node.js 20+
• Perplexity API key (Get one here)

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

• Documentation
• Issues
• Discussions

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

• Perplexity AI for providing the excellent API
• Model Context Protocol for the MCP specification
• Smithery for MCP development tools
• The open-source community for inspiration and contributions

Project Stats

---

Built with for the MCP community