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