# 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](https://www.perplexity.ai/settings/api)
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](https://nodejs.org/)
- **Claude Code CLI** - [Installation guide](https://docs.anthropic.com/claude-code)

### Step 3: Install the MCP Server

#### 3.1 Clone the repository

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

#### 3.2 Install dependencies

**macOS / Linux / Windows:**
```text
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:**
```text
claude mcp add -s user Perplexity -e PERPLEXITY_API_KEY=YOUR_API_KEY -- node /full/path/to/dist/index.js
```

**Windows (CMD):**
```text
claude mcp add -s user Perplexity -e "PERPLEXITY_API_KEY=YOUR_API_KEY" -- node "C:\full\path\to\dist\index.js"
```

**Windows (PowerShell):**
```text
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:**
```text
chmod +x setup.sh
./setup.sh YOUR_API_KEY
```

**Windows (PowerShell):**
```text
.\setup.ps1 -ApiKey YOUR_API_KEY
```

**Or use the npm helper (if API key is set in environment):**
```text
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

```text
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:

```text
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:

```text
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](https://www.perplexity.ai/settings/api)

2. **Check Node.js version** (needs 18+):
   ```text
   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

```text
claude mcp list
```

---

## Contributing

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

## License

MIT

---

Made for the Claude Code community