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

Configuration

HTTP-Only Transport (Aligned with Anthropic's Direction)

Following Anthropic's deprecation of stdio transport in favor of HTTP, this server uses HTTP transport exclusively for both Claude Code and Claude Desktop.

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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
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

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 found

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.

Related MCP Servers

Perplexity AI MCP Server
mkusaka
A
security
A
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 -
270
1
MIT License
Perplexity AI MCP Server
fr0ziii
A
security
F
license
A
quality
This server provides access to the Perplexity AI API, enabling interaction through chatting, searching, and documentation retrieval within MCP-based systems.
Last updated -
2
Perplexity AI MCP Server
rileyedwards77
A
security
F
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
A
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

View all related MCP servers