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

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

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

npm install -g mcp-perplexity-pro

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

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

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

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

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"

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 all conversations in your project.

Retrieve full conversation history.

Parameters:

• chat_id (required): Conversation ID

Create long-running research jobs for complex queries.

Parameters:

• query (required): Research question
• model (optional): Defaults to sonar-deep-research

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 all async jobs in your project.

Get storage statistics and usage information.

Get information about available models and their capabilities.

The server automatically selects the optimal model based on query analysis:

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

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

• 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

# 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

# Set environment variables
export PROJECT_ROOT=/path/to/your/project

# Start production environment
docker-compose up -d

FROM mcp-perplexity-pro:latest

# Custom configuration
COPY my-config.json /app/config.json

# Custom entrypoint
CMD ["node", "dist/index.js", "--config", "config.json"]

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

# 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

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

# 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

// 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',
});

// 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',
});

// 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,
});

• Store API keys securely using environment variables
• Never commit API keys to version control
• Rotate keys regularly
• Use different keys for different environments

• HTTPS in production
• Rate limiting implemented
• Input validation and sanitization
• Error handling without information leakage

• Non-root user execution
• Minimal base images
• Regular security updates
• Vulnerability scanning

# Basic health check
curl http://localhost:3000/health

# Detailed status
curl http://localhost:3000/status

The server exposes Prometheus-compatible metrics:

• Request count and duration
• Error rates by endpoint
• Storage usage statistics
• Model usage distribution

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

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=mcp-perplexity:* npm start

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions

We welcome contributions! Please see our Contributing Guide for details.

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

• TypeScript with strict mode
• ESLint + Prettier formatting
• 100% test coverage for new features
• Conventional commit messages

This project is licensed under the MIT License - see the LICENSE file for details.

• 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

Built with ❤️ for the MCP community