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

MCP Perplexity Pro

Install / Use

README

MCP Perplexity Pro

✨ Features

🚀 Quick Start

Prerequisites

Installation

🚀 Deployment Options

1. NPX Deployment with Transport Mode

2. Docker Deployment (stdio-docker)

3. HTTP Transport (Legacy)

📋 Available Tools

Query Tools

`ask_perplexity`

`research_perplexity`

Chat Tools

`chat_perplexity`

`list_chats_perplexity`

`read_chat_perplexity`

Async Tools

`async_perplexity`

`check_async_perplexity`

`list_async_jobs`

Utility Tools

`storage_stats_perplexity`

`model_info_perplexity`

🧠 Intelligent Model Selection

Model Capabilities

🗂️ Project-Aware Storage

Storage Features

🐳 Docker Deployment

Development

Production

Custom Docker

⚙️ Configuration

Environment Variables