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:

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.

Related MCP server: Perplexity MCP Server

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:

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

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

Configuration

Environment Variables

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:

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