A
securityF
licenseA
qualityThis 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
161
3
Provides AI-powered search, research, and reasoning capabilities through three specialized tools: perplexity_ask for general conversational AI, perplexity_research for deep research with citations, and perplexity_reason for advanced reasoning
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 modelperplexity_research: Deep research with citations using sonar-deep-research modelperplexity_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 endpointPOST /mcp- Main MCP communication endpointGET /mcp- Server-to-client notifications via SSEDELETE /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
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
- -securityAlicense-qualityProvides 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
- AsecurityAlicenseAqualityProvides AI assistants with enhanced reasoning capabilities through structured thinking, persistent knowledge graph memory, and intelligent tool orchestration for complex problem-solving.Last updated -203051MIT License
- -securityAlicense-qualityProvides 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 -13158MIT License