Perplexity MCP Server

A production-ready Model Context Protocol (MCP) server that integrates Perplexity AI's powerful search capabilities. Get real-time AI-powered answers with web sources and citations through the StreamableHTTP transport.

TypeScript Node.js MCP

Overview

This MCP server provides seamless integration with Perplexity AI's chat API, enabling AI applications to access current web information through the Model Context Protocol. Built with TypeScript, Express, and the MCP SDK StreamableHTTP transport for efficient, scalable communication.

Features

✅ Dual Transport Support - Both Stdio (auto-start) and HTTP (standalone) transports
✅ Real-time Web Search - Powered by Perplexity's Sonar Pro model
✅ Rich Responses - AI-generated answers with citations and related images
✅ Flexible Authentication - Supports Authorization header and environment variables
✅ Smart Port Management - Automatic port conflict detection with helpful error messages
✅ Production Ready - Express-based with proper error handling and session management
✅ Universal Compatibility - Works with any MCP client supporting StreamableHTTP or Stdio

Quick Start

Prerequisites

Node.js 18+
pnpm package manager
Perplexity API Key from perplexity.ai

Installation

# Clone or navigate to the project directory cd perplexity-mcp-server # Install dependencies pnpm install # Build the project pnpm build

Running the Server

For HTTP Transport:

# Build and start pnpm build pnpm start

The server will start on http://127.0.0.1:3001/mcp

For Stdio Transport:

No manual start needed - the MCP client launches it automatically. Just configure your client and restart it.

Get Your API Key

Client Configuration

This server provides two transport options:

Transport

Use Case

Pros

When to Use

Stdio

Development, Single Client

✅ Auto-starts

✅ No port conflicts

✅ Simple setup

Cursor IDE, Claude Desktop (single user)

HTTP

Production, Multiple Clients

✅ Serves multiple clients

✅ Stays running

✅ Better for servers

Production deployments, shared environments

Option 1: Stdio Transport (Auto-Start) ⭐ Recommended

The client launches the server automatically. No manual server start required.

Best for: Cursor IDE, Claude Desktop, single-user development

Cursor IDE (Stdio)

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-specific):

{ "mcpServers": { "perplexity": { "command": "node", "args": ["/absolute/path/to/perplexity-mcp-server/dist/stdio.js"], "env": { "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY" } } } }

Note: Replace /absolute/path/to/perplexity-mcp-server with your actual project path.

Claude Desktop (Stdio)

Same configuration format:

{ "mcpServers": { "perplexity": { "command": "node", "args": ["/absolute/path/to/perplexity-mcp-server/dist/stdio.js"], "env": { "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY" } } } }

Option 2: HTTP Transport (Standalone Server) 🚀 Production

Server runs independently and can serve multiple clients.

Best for: Production deployments, shared environments, multiple concurrent clients

Step 1: Start the server

pnpm build pnpm start

Step 2: Configure Cursor

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-specific):

{ "mcpServers": { "perplexity": { "url": "http://127.0.0.1:3001/mcp", "headers": { "Authorization": "Bearer YOUR_PERPLEXITY_API_KEY" } } } }

Step 3: Restart Cursor

The perplexity_search tool will now be available.

Claude Desktop (HTTP)

Same configuration format:

{ "mcpServers": { "perplexity": { "url": "http://127.0.0.1:3001/mcp", "headers": { "Authorization": "Bearer YOUR_PERPLEXITY_API_KEY" } } } }

Note: The server must be running before connecting.

Other MCP Clients

Any MCP client supporting StreamableHTTP can connect using:

Server URL: http://127.0.0.1:3001/mcp
Authentication: Authorization: Bearer YOUR_PERPLEXITY_API_KEY header
Transport: StreamableHTTP (SSE-based)

Refer to your MCP client's documentation for specific configuration steps.

MCP SDK Integration

For direct SDK usage:

import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client( { name: "my-client", version: "1.0.0", }, { capabilities: {}, } ); const transport = new StreamableHTTPClientTransport( new URL("http://127.0.0.1:3001/mcp"), { headers: { Authorization: "Bearer YOUR_API_KEY", }, } ); await client.connect(transport); const result = await client.callTool({ name: "perplexity_search", arguments: { query: "What are the latest developments in quantum computing?", }, }); console.log(result);

Available Tools

`perplexity_search`

Search and get AI-powered answers with real-time web data, citations, and images.

Parameters:

query (string, required): Your search query or question

Example:

{ "query": "What are the latest developments in AI agents?" }

Response includes:

AI-generated answer based on current web data
Sources: Citations with URLs
Related Images: Relevant images with titles and URLs

Model Configuration:

Model: sonar-pro (Perplexity's premier advanced search model)
Search Recency: month (configurable)
Streaming: Enabled (from Perplexity API, processed server-side)
Citations: Included
Images: Included when relevant

Configuration

Environment Variables

PERPLEXITY_API_KEY: Your Perplexity API key (optional if using Authorization header)
PORT: Server port (default: 3001)

API Key Priority

The server accepts API keys from two sources with the following priority:

Authorization Header (Recommended)
- Format: Authorization: Bearer YOUR_API_KEY
- Sent per-request via HTTP headers
- More secure for multi-user scenarios
Environment Variable (Fallback)
- Set PERPLEXITY_API_KEY when starting the server
- Shared across all requests

Usage Examples

With environment variable:

PERPLEXITY_API_KEY=pplx-abc123 PORT=8080 pnpm start

With header authentication:

pnpm start # Client sends: Authorization: Bearer pplx-abc123

Development

Build

pnpm build

Development Mode (with auto-reload)

HTTP Server:

pnpm dev

Stdio Server:

pnpm dev:stdio

Watch TypeScript Compilation

pnpm watch

Test with MCP Inspector

HTTP Server:

pnpm inspector

Stdio Server:

pnpm inspector:stdio

Health Check

Verify the server is running:

curl http://127.0.0.1:3001/health

Expected response:

{ "status": "ok", "service": "perplexity-mcp-server" }

Architecture

StreamableHTTP Transport

This server uses the MCP StreamableHTTP transport providing:

HTTP/HTTPS - Standard protocols for web communication
Server-Sent Events (SSE) - Real-time server-to-client messages
Session Management - Stateful sessions with UUID-based IDs
Scalability - Multiple concurrent connections
Infrastructure Compatibility - Works with proxies, load balancers, and CDNs

Request Flow

Client sends HTTP POST to /mcp endpoint
Express extracts Authorization header → API key
Request forwarded to MCP transport
Tool handler receives request with API key
Server calls Perplexity API with streaming
Response parsed and formatted with citations/images
Complete response returned via MCP protocol

Technology Stack

Runtime: Node.js 18+
Language: TypeScript 5.3+
Framework: Express 5
MCP SDK: @modelcontextprotocol/sdk
HTTP Client: node-fetch 3
Validation: Zod 3

Production Deployment

Security Best Practices

API Key Security
- Use environment variables or secure vaults
- Never commit API keys to version control
- Rotate keys regularly
Network Security
- Server binds to 127.0.0.1 (localhost) by default
- Use reverse proxy (nginx, Caddy) with SSL/TLS for production
- Configure firewall rules appropriately
Input Validation
- All inputs validated with Zod schemas
- Query length limits enforced
Rate Limiting
- Consider adding rate limiting middleware
- Monitor Perplexity API usage

Reverse Proxy Example (nginx)

server { listen 443 ssl http2; server_name mcp.yourdomain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location /mcp { proxy_pass http://127.0.0.1:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

Process Management (PM2)

# Install PM2 npm install -g pm2 # Start server pm2 start dist/server.js --name perplexity-mcp # With environment variables pm2 start dist/server.js --name perplexity-mcp \ --env PERPLEXITY_API_KEY=your-key \ --env PORT=3001 # Save process list pm2 save # Setup startup script pm2 startup

Docker Deployment

FROM node:18-alpine WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN npm install -g pnpm && pnpm install --frozen-lockfile COPY . . RUN pnpm build EXPOSE 3001 CMD ["node", "dist/server.js"]

Troubleshooting

Common Issues

Error: "PERPLEXITY_API_KEY is required"

Ensure API key is provided via Authorization header or environment variable
Check header format: Authorization: Bearer YOUR_KEY
Verify the server receives the header (check logs)

Connection Refused

Verify server is running: curl http://127.0.0.1:3001/health
Check port matches configuration
Ensure no firewall is blocking the port

Citations or Images showing as "Untitled" or broken links

This should be fixed in the latest version
Rebuild: pnpm build && pnpm start
Verify you're running the latest code

Error: "Port 3001 is already in use"

The server automatically detects port conflicts and provides helpful solutions:

❌ ERROR: Port 3001 is already in use! Process: PID 12345: node dist/server.js 💡 To fix this, you can: 1. Stop the existing server (Ctrl+C in its terminal) 2. Use a different port: PORT=3002 pnpm start 3. Kill the process: kill -9 $(lsof -ti:3001) 4. Find and stop it: lsof -ti:3001 | xargs ps -p

Cursor IDE not finding server (HTTP)

Ensure server is running before starting Cursor: pnpm start
Check ~/.cursor/mcp.json syntax is valid JSON
Fully restart Cursor (Cmd+Q / Ctrl+Q, then relaunch)
Verify server is running: curl http://127.0.0.1:3001/health
Check Cursor's MCP panel for connection status

Cursor IDE - Stdio vs HTTP

Stdio (Recommended): Auto-starts, no manual server needed
HTTP: Requires pnpm start running in a separate terminal
If HTTP not connecting, try Stdio instead for simplicity

API Reference

Perplexity API

Documentation: https://docs.perplexity.ai/
API Reference: https://docs.perplexity.ai/api-reference/chat-completions
Model Cards: https://docs.perplexity.ai/guides/model-cards

Model Context Protocol

MCP Docs: https://modelcontextprotocol.io/
Specification: https://spec.modelcontextprotocol.io/
TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

Project Structure

perplexity-mcp-server/ ├── src/ │ ├── server.ts # HTTP transport server (StreamableHTTP) │ └── stdio.ts # Stdio transport server (auto-start) ├── dist/ # Compiled JavaScript output │ ├── server.js # HTTP server executable │ └── stdio.js # Stdio server executable ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── mcp.json.example # Example MCP client config └── README.md # This file

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Acknowledgments

Built with:

Made with ❤️ using the Model Context Protocol

Support

📖 Documentation
🐛 Report Issues
🌟 Star this repo if you find it useful!

Deploy Server

HTTP connection URL

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

perplexity_search_chat

Integrates Perplexity AI's chat capabilities with real-time web search, enabling users to ask questions and receive AI-powered answers with up-to-date information and citations from verified web sources.