Perplexity MCP Server

MCP server that brings Perplexity to Claude Code — AI-powered web search, deep research, reasoning, brainstorming, code review, explanations, and file analysis. All with real-time web grounding and citations. Supports Sonar, Sonar Pro, Sonar Reasoning Pro, and Sonar Deep Research models.

Quick Start

Step 1: Get Your API Key

1. Go to Perplexity API Settings
2. Create an account or sign in
3. Generate an API key
4. Copy the key (you'll need it in Step 3)

Step 2: Install Prerequisites

• Node.js 18+ - Download here
• Claude Code CLI - Installation guide

Step 3: Install the MCP Server

3.1 Clone the repository

git clone https://github.com/wynandw87/claude-code-perplexity-mcp.git
cd claude-code-perplexity-mcp

3.2 Install dependencies

macOS / Linux / Windows:

npm install

Note: Dependencies are installed and the server is built automatically in one step.

3.3 Register with Claude Code

Choose your install scope:

Scope	Flag	Who can use it
User (recommended)	-s user	You, in any project
Project	-s project	Anyone who clones this repo
Local	-s local	Only in current directory

Replace YOUR_API_KEY with your actual Perplexity API key, and use the full path to dist/index.js.

Tip: To get the full path, run this from the cloned directory:

• macOS/Linux: echo "$(pwd)/dist/index.js"
• Windows: echo %cd%\dist\index.js

macOS / Linux:

claude mcp add -s user Perplexity -e PERPLEXITY_API_KEY=YOUR_API_KEY -- node /full/path/to/dist/index.js

Windows (CMD):

claude mcp add -s user Perplexity -e "PERPLEXITY_API_KEY=YOUR_API_KEY" -- node "C:\full\path\to\dist\index.js"

Windows (PowerShell):

claude mcp add -s user Perplexity -e "PERPLEXITY_API_KEY=YOUR_API_KEY" '--' node "C:\full\path\to\dist\index.js"

Alternative: Use Setup Scripts

The setup scripts handle dependency installation, building, and registration automatically.

macOS / Linux:

chmod +x setup.sh
./setup.sh YOUR_API_KEY

Windows (PowerShell):

.\setup.ps1 -ApiKey YOUR_API_KEY

Or use the npm helper (if API key is set in environment):

export PERPLEXITY_API_KEY=YOUR_API_KEY
npm run install:claude

Step 4: Restart Claude Code

Close and reopen Claude Code for the changes to take effect.

Step 5: Verify Installation

claude mcp list

You should see Perplexity listed with a Connected status.

---

Features

Search & Research

• Web Search (search_web) - AI-powered web search with domain filtering, recency filtering, and detailed citations
• Deep Research (deep_research) - Exhaustive multi-step research using sonar-deep-research
• Reasoning + Search (search_with_reasoning) - Step-by-step reasoning combined with live web search
• Raw Search (search) - Ranked search results with titles, URLs, and snippets

Text & Analysis

• General Queries (ask) - Web-grounded Q&A with automatic citations
• Brainstorming (brainstorm) - Creative ideation informed by real-time web data
• Code Review (code_review) - Code analysis with web-grounded best practices
• Explanations (explain) - Clear concept explanations with web-grounded accuracy

Files

• File Upload (upload_file) - Upload documents and images for analysis (text files, images)

---

Usage

Once installed, use trigger phrases to invoke Perplexity:

Trigger	Tool	Example
use perplexity, ask perplexity	Ask	"ask perplexity about quantum computing"
perplexity search, perplexity web search	Web Search	"perplexity search: latest React 19 features"
perplexity research, perplexity deep research	Deep Research	"perplexity deep research on Rust vs Go for microservices"
perplexity reason, perplexity think	Reasoning	"perplexity reason about RSC vs traditional SSR performance"
perplexity raw search, perplexity search results	Raw Search	"perplexity raw search for MCP server TypeScript examples"
perplexity review, have perplexity review	Code Review	"perplexity review this function for security"
perplexity brainstorm, perplexity ideas	Brainstorm	"perplexity brainstorm ideas for authentication"
perplexity explain	Explain	"perplexity explain how WebSockets work"
perplexity upload file	Upload File	"perplexity upload ./report.py and review it"

Or ask naturally:

• "Ask Perplexity what the latest best practices are for Next.js"
• "Have Perplexity review this code for security issues"
• "Brainstorm with Perplexity about scaling strategies"
• "Perplexity search the web for the latest news on AI"
• "Do a deep research with Perplexity on the state of WebAssembly"
• "Perplexity reason through the tradeoffs of microservices vs monolith"
• "Upload this CSV to Perplexity and ask it to summarize the data"

---

Tool Reference

ask

Query Perplexity with web-grounded answers and citations.

Parameters:

• prompt (string, required) - The question or instruction
• model (string, optional) - Model identifier (defaults to sonar-pro)
• search (boolean, optional) - Enable web search grounding (default: true)

search_web

Search the web with domain and recency filtering. Best-in-class AI search.

Parameters:

• query (string, required) - The search query or question
• allowed_domains (string[], optional) - Only include results from these domains (max 5)
• excluded_domains (string[], optional) - Exclude these domains from search (max 5)
• recency (string, optional) - "hour", "day", "week", "month"
• detail (string, optional) - Search depth: "low", "medium", "high"

deep_research

Conduct exhaustive, multi-step research on a topic. May take 30-60+ seconds.

Parameters:

• query (string, required) - The research question or topic to investigate

search_with_reasoning

Step-by-step reasoning combined with live web search.

Parameters:

• prompt (string, required) - The question or problem requiring deep reasoning
• allowed_domains (string[], optional) - Only include results from these domains (max 5)
• recency (string, optional) - "hour", "day", "week", "month"

search

Get raw ranked search results without AI synthesis.

Parameters:

• query (string, required) - The search query
• max_results (integer, optional) - Number of results (1-50, default: 10)
• domain_filter (string[], optional) - Filter to these domains only (max 5)
• recency (string, optional) - "hour", "day", "week", "month"

code_review

Code review with web-grounded current best practices.

Parameters:

• code (string, required) - The code to review
• focus (string, optional) - Specific focus area (e.g., "security", "performance")

brainstorm

Brainstorming informed by real-time web data and current trends.

Parameters:

• topic (string, required) - The subject to brainstorm about
• context (string, optional) - Additional context

explain

Clear explanations with web-grounded accuracy.

Parameters:

• concept (string, required) - What to explain

upload_file

Upload a document or image for analysis.

Parameters:

• file_path (string, required) - Absolute path to the file to upload
• query (string, optional) - Question to ask about the file immediately after upload
• model (string, optional) - Model identifier (defaults to sonar-pro)

Supports text files (.txt, .md, .py, .js, .ts, .csv, .json, etc.) and images (.png, .jpg, .gif, .webp).

---

Supported Models

Model	Best For
sonar	Quick queries, summaries — fast and cost-effective
sonar-pro	Default — complex queries, citations, multi-step reasoning
sonar-reasoning-pro	Multi-step reasoning with live web search
sonar-deep-research	Exhaustive research, comprehensive reports

All models have 128K context windows and real-time web grounding.

---

Configuration

Environment Variables

Variable	Required	Default	Description
PERPLEXITY_API_KEY	Yes	—	Perplexity API key
PERPLEXITY_DEFAULT_MODEL	No	sonar-pro	Default model for text tools
PERPLEXITY_TIMEOUT	No	60000	API timeout in ms

---

How It Works

This MCP server uses the Perplexity REST API directly (Chat Completions and Search endpoints) with native fetch. No SDK dependency — just @modelcontextprotocol/sdk and zod. It connects to Claude Code via stdio transport.

Tools provided:

Tool	API	Default Model
ask	Chat Completions	Configurable (sonar-pro)
search_web	Chat Completions + domain/recency filters	sonar-pro
deep_research	Chat Completions	sonar-deep-research
search_with_reasoning	Chat Completions	sonar-reasoning-pro
search	Search API	—
code_review	Chat Completions	sonar-pro
brainstorm	Chat Completions	sonar-pro
explain	Chat Completions	sonar
upload_file	Chat Completions (inline/vision)	Configurable (sonar-pro)

---

Troubleshooting

Fix API Key

If you entered the wrong API key, remove and reinstall:

claude mcp remove Perplexity

Then reinstall using the command from Step 3.3 above (use the same scope you originally installed with).

MCP Server Not Showing Up

Check if the server is installed:

claude mcp list

If not listed, follow Step 3 to install it.

Server Won't Start

1. Verify your API key is valid at Perplexity API Settings

2. Check Node.js version (needs 18+):

   node --version
   

3. Ensure the server was built — if dist/index.js is missing, run npm install again

Connection Errors

1. Check that dist/index.js exists — if not, run npm install
2. Verify the path is absolute in your claude mcp add command
3. Restart Claude Code after any configuration changes

Timeout Errors

• Deep research uses 5x base timeout — it's expected to take longer
• Reasoning and search tools use 3x base timeout
• Increase PERPLEXITY_TIMEOUT environment variable for slow connections

Deep Research Takes Too Long

sonar-deep-research can take 30-60+ seconds for comprehensive research. This is normal — it's doing multi-step investigation across many sources.

View Current Configuration

claude mcp list

---

Contributing

Pull requests welcome! Please keep it simple and beginner-friendly.

License

MIT

---

Made for the Claude Code community