Skip to main content
Glama
cfdude

MCP Perplexity Pro

by cfdude
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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-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

Related MCP server: Perplexity AI MCP Server

🚀 Quick Start

Prerequisites

Installation

npm install -g mcp-perplexity-pro

🚀 Deployment Options

1. NPX Deployment with Transport Mode

The recommended way to use the MCP server with explicit transport control:

For Claude Desktop (claude_desktop_config.json):

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

For Claude Code (.mcp.json):

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

Alternative: Use the dedicated stdio binary (legacy):

{ "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:

  • topic (required): Research topic or question

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

  • save_report (optional): Save report to project directory (default: true)

  • project_name (optional): Project name for organizing reports (auto-detected if not provided)

  • max_tokens (optional): Maximum response length

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. By default, excludes full content to save context and auto-saves completed reports.

Parameters:

  • job_id (required): Job identifier

  • include_content (optional): Include full response content (default: false to save context)

  • save_report (optional): Save completed report to project directory (default: true)

  • project_name (optional): Project name for saving report (auto-detected if not provided)

Returns: Job status, and when complete: report_path showing where the report was saved.

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

Quick factual 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-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
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

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