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

$3

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

$3

``bash
npm install -g mcp-perplexity-pro
`

🚀 Deployment Options

$3

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

For Claude Desktop (claude_desktop_config.json):

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

For Claude Code (.mcp.json):

`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):

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

$3

Run the MCP server in a Docker container with stdio transport:

Using Docker Compose:

`bash


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

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

`bash
docker run -it --rm \
-e PERPLEXITY_API_KEY="your-api-key-here" \
-v "$(pwd)/data:/app/data" \
mcp-perplexity-pro:stdio
`

$3

For Claude Code (.mcp.json):

`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):

`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

$3

#### 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"
`

$3

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

$3

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

$3

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

$3

`typescript
{
"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
`

$3

- 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

$3

`bash


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
`

$3

`bash


Set environment variables

export PROJECT_ROOT=/path/to/your/project

Start production environment

docker-compose up -d
`

$3

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

$3

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

$3

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

🧪 Development

$3

`bash


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
`

$3

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

$3

`bash


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

$3

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

$3

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

$3

`javascript
// 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

$3

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

$3

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

$3

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

📈 Monitoring

$3

`bash


Basic health check

curl http://localhost:3000/health

Detailed status

curl http://localhost:3000/status
`

$3

The server exposes Prometheus-compatible metrics:

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

$3

Structured JSON logging with configurable levels:

`json
{
"timestamp": "2024-08-20T19:00:00.000Z",
"level": "info",
"message": "Query processed successfully",
"model": "sonar-reasoning-pro",
"duration": 1250,
"session_id": "session-123"
}
`

🚨 Troubleshooting

$3

API Key Errors

`bash
Error: Invalid API key
Solution: Verify PERPLEXITY_API_KEY is set correctly
`

Storage Permission Errors

`bash
Error: EACCES: permission denied
Solution: Ensure storage directory is writable
`

Model Selection Issues

`bash
Error: Model not available
Solution: Check model name spelling and availability
`

$3

`bash
DEBUG=mcp-perplexity:* npm start
``

$3

- 📚 Documentation
- 🐛 Issues
- 💬 Discussions

🤝 Contributing

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

$3

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

$3

- 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

!GitHub stars
!GitHub forks
!GitHub issues
!GitHub pull requests

---

Built with ❤️ for the MCP community