sergekostenchuk/perplexity-pro-mcp

Perplexity Pro MCP

High-performance MCP (Model Context Protocol) server for Perplexity API integration with multi-threading support.

Высокопроизводительный MCP (Model Context Protocol) сервер для интеграции с Perplexity API с поддержкой многопоточности.

🔍 Complete Functionality Overview (EN)

Core Commands

search(query, options?)

Single query search with configurable options

• Parameters: query (required), model, max_tokens
• Example: search("What is quantum computing?")

multiSearch(queries[], options?)

Parallel execution of up to 5 searches simultaneously

• Limit: maximum 5 queries
• Progress: real-time progress tracking
• Example: multiSearch(["AI trends", "Quantum computing", "Climate tech"])

deepResearch(topic, depth?)

Multi-level topic exploration with automatic branching (1-3 levels)

• Depth: 1-3 levels (default: 2)
• Branching: up to 5 subtopics per level
• Auto-analysis: key insights extraction
• Example: deepResearch("Future of renewable energy", 3)

Specialized Commands

factCheck(statement)

Fact verification with credible sources

• Model: sonar-pro for accuracy
• Output: true/false/partially true + sources

codeSearch(query, language?)

Code examples and documentation search

• Languages: optional programming language specification
• Output: code examples + documentation

recentSearch(query, days?)

Recent information search (default: 7 days)

• Range: 1-30 days
• Focus: news and latest developments

academicSearch(query)

Scientific papers and research search

• Output: academic sources + citations

Performance Features

• HTTP/2 Connection Pooling: Minimal latency with persistent connections
• Smart Caching: Content-aware TTL strategies
• Real-time Progress: Visual feedback for long operations
• Error Handling: Automatic retries with exponential backoff
• Performance Monitoring: Built-in statistics and metrics

Benchmarks

🔍 Полное описание функционала (RU)

Основные команды

search(query, options?)

Базовый поиск с одним запросом

• Параметры: query (обязательно), model, max_tokens
• Пример: search("Что такое квантовые вычисления?")

multiSearch(queries[], options?)

Параллельный поиск до 5 запросов одновременно

• Лимит: максимум 5 запросов
• Прогресс: отображение в реальном времени
• Пример: multiSearch(["AI тренды", "Квантовые компьютеры", "Климат технологии"])

deepResearch(topic, depth?)

Многоуровневое исследование темы (1-3 уровня глубины)

• Глубина: 1-3 уровня (по умолчанию 2)
• Ветвление: до 5 подтем на уровень
• Автоанализ: извлечение ключевых инсайтов
• Пример: deepResearch("Будущее возобновляемой энергии", 3)

Специализированные команды

factCheck(statement)

Проверка фактов с источниками

• Модель: sonar-pro для точности
• Выход: правда/ложь/частично правда + источники

codeSearch(query, language?)

Поиск кода и документации

• Языки: опционально указать язык программирования
• Результат: примеры кода + документация

recentSearch(query, days?)

Поиск свежей информации (по умолчанию 7 дней)

• Диапазон: 1-30 дней
• Фокус: новости и последние разработки

academicSearch(query)

Поиск научных статей и исследований

• Результат: академические источники + цитаты

Особенности производительности

• HTTP/2 Connection Pooling: Минимальная задержка через постоянные соединения
• Smart Caching: Контекстно-зависимое кеширование с разными TTL
• Прогресс в реальном времени: Визуальная обратная связь для длительных операций
• Обработка ошибок: Автоматические повторы с экспоненциальным backoff
• Мониторинг производительности: Встроенная статистика и метрики

Производительность

Features (EN)

• ⚡ HTTP/2 Connection Pooling - Minimal latency with persistent connections
• 🔄 Parallel Search - Execute up to 5 searches simultaneously
• 🧐 Deep Research - Multi-level exploration with automatic topic branching
• 💾 Smart Caching - Content-aware TTL strategies for optimal performance
• 📊 Real-time Progress - Visual feedback for long-running operations
• 🛡️ Robust Error Handling - Automatic retries with exponential backoff
• 📈 Performance Monitoring - Built-in statistics and metrics

Installation

Quick Install (Recommended)

npx @mlllm/perplexity-pro-mcp

This will:

• Check Node.js compatibility (requires v20+)
• Prompt for your Perplexity API key
• Test the API connection
• Configure Claude Desktop automatically
• Build and install the MCP server

Manual Install

# Clone the repository
git clone https://github.com/sergekostenchuk/perplexity-pro-mcp.git
cd perplexity-pro-mcp

# Install dependencies
npm install

# Set your API key
export PERPLEXITY_API_KEY=your-api-key-here

# Build the project
npm run build

# Run the installer
npm run install-local

Available Commands

Main Search Commands

search(query, options?)

Perform a single search query.

// In Claude Desktop
search("What are the latest developments in quantum computing?")

// With options
search("Explain transformer architecture", {
  model: "pplx-70b-online",
  max_tokens: 2000
})

multiSearch(queries[], options?)

Execute multiple searches in parallel (up to 5).

multiSearch([
  "Latest AI breakthroughs 2024",
  "Quantum computing applications",
  "Climate technology innovations"
])

deepResearch(topic, depth?)

Perform comprehensive multi-level research on a topic.

// Basic research (2 levels deep)
deepResearch("Future of renewable energy")

// Exhaustive research (3 levels)
deepResearch("CRISPR gene editing applications", 3)

Specialized Commands

factCheck(statement)

Verify facts and claims with sources.

factCheck("The moon landing happened in 1969")

codeSearch(query, language?)

Search for code examples and documentation.

codeSearch("binary search implementation", "python")
codeSearch("React hooks best practices")

recentSearch(query, days?)

Find information from recent timeframes.

recentSearch("OpenAI announcements", 7)
recentSearch("Stock market news", 1)

academicSearch(query)

Search academic papers and research.

academicSearch("machine learning in healthcare")

Utility Commands

• help() - Display all available commands with examples
• stats() - Show connection and cache statistics
• config() - Display current configuration
• clearCache() - Clear the response cache

Configuration

Environment Variables

PERPLEXITY_API_KEY=your-api-key-here

Claude Desktop Configuration

The installer automatically adds this configuration:

{
  "mcpServers": {
    "perplexity-pro": {
      "command": "node",
      "args": ["/path/to/perplexity-pro-mcp/dist/index.js"],
      "env": {
        "PERPLEXITY_API_KEY": "your-api-key"
      }
    }
  }
}

API Client Usage

TypeScript/JavaScript

import { PerplexityClient } from '@mlllm/perplexity-pro-mcp';

const client = new PerplexityClient({
  apiKey: process.env.PERPLEXITY_API_KEY,
  maxConnections: 5,
  timeout: 30000,
});

// Simple search
const result = await client.search({
  query: 'What is quantum entanglement?',
  options: {
    model: 'pplx-70b-online',
    max_tokens: 1500,
  },
});

// Multi-search
const multiResults = await client.multiSearch(
  ['AI trends', 'Robotics advances', 'Neural interfaces'],
  { model: 'pplx-70b-online' }
);

// Stream responses
const stream = client.streamSearch({
  query: 'Explain machine learning',
  options: { stream: true }
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

// Get statistics
console.log(client.getConnectionStats());

Performance

Benchmarks

Caching Strategy

Advanced Features

Progress Tracking

Multi-search operations provide real-time progress updates:

const results = await multiSearch([...queries], {
  showProgress: true
});

// Output:
// Processing batch 1
// ✓ Completed: "AI trends" (187ms)
// ✓ Completed: "Robotics" (234ms)
// ...

Connection Pool Monitoring

stats()

// Output:
// Active connections: 2
// Idle connections: 3
// Average response time: 267ms
// Cache hit rate: 67%

Error Handling

The client implements intelligent retry logic:

• Network errors: 3 retries with exponential backoff
• Rate limits (429): Automatic throttling
• Server errors (5xx): Configurable retry attempts

Development

Project Structure

perplexity-pro-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── api/              # HTTP client implementation
│   ├── cache/            # Caching strategies
│   ├── engines/          # Search engines (multi, deep)
│   ├── mcp/              # MCP protocol handlers
│   └── utils/            # Logging and helpers
├── tests/                # Test suites
├── scripts/              # Installation scripts
└── dist/                 # Compiled output

Running Tests

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Building

# Development build
npm run build

# Production build
npm run build:prod

Troubleshooting

Common Issues

1. "API key is invalid"

   • Verify your API key at https://www.perplexity.ai/settings/api
   • Ensure no extra spaces in the key

2. "Claude Desktop not found"

   • The installer will provide manual configuration steps
   • Check the config location for your OS

3. "Connection timeout"

   • Check your internet connection
   • Verify firewall settings allow HTTPS to api.perplexity.ai

4. "Rate limit exceeded"

   • The client automatically handles rate limits
   • Reduce parallel requests if persistent

Debug Mode

Enable detailed logging:

export DEBUG=perplexity:*
export NODE_ENV=development

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details

Acknowledgments

• Built for Claude Desktop
• Powered by Perplexity AI
• Uses the Model Context Protocol

Version: 2.0.0
Author: kostenchuksergey
Repository: GitHub