MCP Perplexity Server

MCP server for Perplexity.ai that provides AI-powered search, research, and reasoning capabilities.

🚀 Features

Perplexity AI Integration: Three specialized tools for different use cases
- perplexity_ask: General conversational AI using sonar-pro model
- perplexity_research: Deep research with citations using sonar-deep-research model
- perplexity_reason: Advanced reasoning using sonar-reasoning-pro model
TypeScript: Full type safety with modern TypeScript patterns
HTTP Transport: RESTful API with Express.js server
Session Management: Stateful connections with proper session handling
Configuration Management: Environment-based configuration with validation
Error Handling: Comprehensive error handling and logging
Health Checks: Built-in health monitoring endpoints
Docker Support: Production-ready containerization
Development Tools: ESLint, Prettier, and testing setup
Production Ready: Optimized for scalability and security

📋 Prerequisites

Node.js 20+
npm or yarn
Docker (optional, for containerization)

🛠️ Quick Start

Option 1: Use the Project Generator (Recommended)

# Clone the template
git clone <your-repo-url>
cd mcp-perplexity


# Create a new project using the generator
./create-mcp-project your-project-name --description "Your project description" --author "Your Name"

# Or use the Node.js script directly
node setup-new-project.js your-project-name --description "Your project description" --author "Your Name"

Generator Options:

--description <desc>: Project description
--author <name>: Author name
--target-dir <dir>: Target directory (default: mcp-)
--install-deps: Install npm dependencies automatically
--no-git: Skip git repository initialization

Option 2: Manual Setup

# Clone the template
git clone <your-repo-url>
cd mcp-template

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env  # Create this file with your settings

2. Environment Configuration

Create a .env file in the root directory:

# Server Configuration
PORT=3000
LOG_LEVEL=info

# Perplexity API Configuration
PERPLEXITY_API_KEY=your_perplexity_api_key_here

3. Development

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test

# Lint and format code
npm run lint
npm run lint:fix

🏗️ Project Structure

mcp-perplexity/
├── src/
│   ├── config/           # Configuration management
│   │   └── index.ts      # Main config file
│   ├── services/         # Service layer
│   │   └── perplexity.ts # Perplexity API service
│   ├── utils/            # Utility functions
│   └── index.ts          # Main server application
├── create-mcp-project    # Bash script for project generation
├── setup-new-project.js  # Node.js project generator
├── Dockerfile            # Docker configuration
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

🔧 Project Generator

This template includes powerful project generation tools to quickly create new MCP servers:

Features:

Automatic Name Conversion: Converts kebab-case names to all required formats (camelCase, PascalCase, etc.)
File Templating: Updates all files with the new project name and details
Git Integration: Optionally initializes a new git repository
Dependency Management: Can automatically install npm dependencies
Smart Copy Logic: Excludes development files and prevents infinite recursion

Usage Examples:

# Basic usage
./create-mcp-project weather-service

# With full options
./create-mcp-project task-manager \
  --description "AI-powered task management MCP server" \
  --author "Your Name" \
  --install-deps

# Custom target directory
./create-mcp-project file-processor --target-dir ./my-custom-server

# Skip git initialization
./create-mcp-project data-analyzer --no-git

🔧 Architecture

Core Components

McpServerApp: Main application class that orchestrates the MCP server
Configuration: Environment-based configuration with type safety
Session Management: HTTP-based stateful sessions with cleanup
Transport Layer: StreamableHTTPServerTransport for MCP communication
Error Handling: Comprehensive error handling with proper HTTP responses

HTTP Endpoints

GET /health - Health check endpoint
POST /mcp - Main MCP communication endpoint
GET /mcp - Server-to-client notifications via SSE
DELETE /mcp - Session termination

🛠️ Customization Guide

Using Perplexity Tools

The server provides three Perplexity AI tools:

1. perplexity_ask

General conversational AI using the sonar-pro model.

{
  "name": "perplexity_ask",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "What are the latest developments in AI?"
      }
    ]
  }
}

2. perplexity_research

Deep research with citations using the sonar-deep-research model.

{
  "name": "perplexity_research",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Research the current state of quantum computing and its applications"
      }
    ]
  }
}

3. perplexity_reason

Advanced reasoning using the sonar-reasoning-pro model.

{
  "name": "perplexity_reason",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Analyze the pros and cons of different renewable energy sources"
      }
    ]
  }
}

Adding New Tools

To add a new MCP tool, modify the createServer() method in src/index.ts:

// Register your custom tool
server.tool(
  'your-tool-name',
  'Description of your tool',
  {
    // Define input schema using Zod
    parameter1: z.string().describe('Parameter description'),
    parameter2: z.number().optional().describe('Optional parameter'),
  },
  async ({ parameter1, parameter2 }) => {
    try {
      // Your tool implementation here
      const result = await yourCustomLogic(parameter1, parameter2);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          } as TextContent,
        ],
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      throw new Error(`Error in your-tool-name: ${errorMessage}`);
    }
  }
);

Configuration Management

Add new configuration options in src/config/index.ts:

interface Config {
  logging: LoggingConfig;
  server: ServerConfig;
  // Add your custom config sections
  database: {
    url: string;
    timeout: number;
  };
  external: {
    apiKey: string;
    baseUrl: string;
  };
}

const config: Config = {
  // ... existing config
  database: {
    url: process.env.DATABASE_URL || 'sqlite://memory',
    timeout: parseInt(process.env.DB_TIMEOUT || '5000', 10),
  },
  external: {
    apiKey: process.env.EXTERNAL_API_KEY || '',
    baseUrl: process.env.EXTERNAL_BASE_URL || 'https://api.example.com',
  },
};

Adding Middleware

Add Express middleware in the run() method:

async run() {
  const app = express();
  app.use(express.json());

  // Add your custom middleware
  app.use(cors()); // CORS support
  app.use(helmet()); // Security headers
  app.use(morgan('combined')); // Request logging

  // ... rest of the setup
}

🐳 Docker Deployment

Build and Run

# Build Docker image
docker build -t mcp-perplexity-server .

# Run container
docker run -p 3000:3000 --env-file .env mcp-perplexity-server

Docker Compose (Recommended)

Create a docker-compose.yml:

version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3

Run with:

docker-compose up -d

🔒 Security Best Practices

This template implements several security measures:

Input Validation: Zod schema validation for all tool parameters
Error Handling: Safe error responses without information leakage
Session Management: Proper session cleanup and validation
HTTP Security: Ready for security headers and CORS configuration
Environment Variables: Secure configuration management

Recommended Additional Security

// Add security middleware
import helmet from 'helmet';
import cors from 'cors';
import rateLimit from 'express-rate-limit';

app.use(helmet());
app.use(
  cors({
    origin: process.env.ALLOWED_ORIGINS?.split(',') || false,
  })
);

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Limit each IP to 100 requests per windowMs
});
app.use('/mcp', limiter);

📊 Monitoring and Logging

The template includes basic logging setup. For production, consider adding:

Structured Logging: Winston with JSON format
Metrics Collection: Prometheus metrics
Health Checks: Comprehensive health endpoints
APM Integration: Application Performance Monitoring

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Writing Tests

Create test files in src/**/*.test.ts:

import { describe, test, expect } from '@jest/globals';
// Your test imports

describe('YourComponent', () => {
  test('should handle valid input', async () => {
    // Test implementation
  });
});

🚀 Production Deployment

Environment Variables

NODE_ENV=production
PORT=3000
LOG_LEVEL=warn

# Add your production-specific variables
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
API_KEYS=...

Performance Optimization

Enable gzip compression
Implement proper caching headers
Use connection pooling for databases
Monitor memory usage and implement limits
Set up log rotation

Scaling Considerations

Load balancing across multiple instances
Database connection pooling
Session store externalization (Redis)
Horizontal pod autoscaling in Kubernetes

📚 References

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

📝 License

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

🆘 Support

For questions and support:

Check the MCP Documentation
Review existing issues
Create a new issue with detailed information

Happy coding! 🎉

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

Provides AI-powered search, research, and reasoning capabilities through integration with Perplexity.ai, offering three specialized tools: general conversational AI, deep research with citations, and advanced reasoning.

Related MCP Servers

Perplexity MCP Server
spragginsdesigns
A
security
F
license
A
quality
This server allows users to perform web searches using Perplexity AI, providing a tool for retrieving search results through a simple API interface.
Last updated -
1
51
3
Perplexity MCP Server
sengokudaikon
-
security
A
license
-
quality
Provides access to Perplexity AI models through two tools: ask\_perplexity for expert programming assistance and chat\_perplexity for maintaining ongoing conversations with context preservation.
Last updated -
MIT License
MCP Think Tank
flight505
A
security
A
license
A
quality
Provides AI assistants with enhanced reasoning capabilities through structured thinking, persistent knowledge graph memory, and intelligent tool orchestration for complex problem-solving.
Last updated -
20
85
44
MIT License
Octagon Deep Research MCPofficial
OctagonAI
-
security
A
license
-
quality
Provides specialized AI-powered comprehensive research and analysis capabilities by integrating with advanced deep research agents, offering unlimited queries with no rate limits and faster performance than comparable services.
Last updated -
168
49
MIT License

View all related MCP servers