# Perplexity MCP Server

Exposes Perplexity AI's search and synthesis capabilities through the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/python-sdk), enabling Claude Desktop and other MCP clients to search the web, synthesize sources, and get cited answers.

```
Claude Desktop
    ↓ stdio
Perplexity MCP Server
    ├── perplexity_ask       → Ask a question, get answer + sources
    ├── perplexity_search    → In-depth web search
    ├── set_cookies          → Set Perplexity cookies (JSON / Netscape format)
    ├── list_models          → List available models
    └── reset_conversation   → Reset conversation context
    ↓
PerplexityClient (curl_cffi → Chrome impersonation → Cloudflare bypass)
    ↓
Perplexity.ai internal API (SSE)
```

## Installation

```bash
pip install -r requirements.txt
```

Requires **Python 3.10+**. Only two dependencies:
- [`curl_cffi`](https://github.com/yifeikong/curl_cffi) — TLS fingerprint impersonation (Chrome 120)
- [`mcp`](https://github.com/modelcontextprotocol/python-sdk) — Model Context Protocol SDK

## Getting Cookies

This MCP server uses Perplexity's internal API, which requires valid session cookies. Choose one of the following methods:

### Method 1: Browser Export (Recommended)

1. Log in to [Perplexity.ai](https://www.perplexity.ai) in Chrome
2. Open DevTools → Application → Cookies → `www.perplexity.ai`
3. Export all cookies as JSON
4. Save to `cookies/perplexity_cookies.json`

### Method 2: Playwright (Automated)

```bash
pip install playwright
playwright install chromium
python get_cookies.py
# Browser opens → log in to Perplexity → press Enter in terminal
```

For headless mode: `python get_cookies.py --headless`

### Method 3: Netscape Format

Export cookies from any browser in Netscape format and save to `cookies/perplexity_cookies.txt`. The server reads them automatically.

### Method 4: Environment Variable

```bash
export PERPLEXITY_COOKIES_JSON='{"cookie_name": "value", ...}'
```

### Method 5: MCP Tool (Runtime)

If you already have cookie values (e.g., from another AI agent), use the `set_cookies` tool at runtime. It accepts both JSON and Netscape formats:

```json
{
  "cookies_data": "{\"__Secure-next-auth.session-token\": \"...\", \"cf_clearance\": \"...\"}"
}
```

or Netscape format:

```json
{
  "cookies_data": ".perplexity.ai\ttrue\t/\ttrue\t1787873851\tcookie_name\tcookie_value"
}
```

This is especially useful when an AI agent possesses cookie values and needs to configure the MCP server without filesystem access.

## Usage

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "perplexity": {
      "command": "python",
      "args": ["C:/full/path/to/mcp_server.py"]
    }
  }
}
```

### Cursor / VS Code

Add to `.cursor/mcp.json` or VS Code MCP settings:

```json
{
  "mcpServers": {
    "perplexity": {
      "command": "python",
      "args": ["C:/full/path/to/mcp_server.py"]
    }
  }
}
```

### Direct Testing

```bash
# Start the MCP server
python mcp_server.py

# In another terminal, test with MCP Inspector
npx @modelcontextprotocol/inspector python mcp_server.py
```

## Tools

### `perplexity_ask`

Ask a question. Perplexity searches the web and returns a cited answer.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `message` | string | **required** | Question or topic |
| `model` | string | `"auto"` | Model: `gpt-4o`, `claude-4.5-sonnet`, `o3-mini`, `deepseek-r1`, ... |
| `search_focus` | enum | `"internet"` | `"internet"` or `"writing"` |
| `sources` | string[] | `["web"]` | Sources: `web`, `scholar`, `social`, `edgar` |

### `perplexity_search`

In-depth web search. An alias for `perplexity_ask` with different default parameters focused on search.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | **required** | Search query |
| `search_focus` | enum | `"internet"` | `"internet"` or `"writing"` |
| `sources` | string[] | `["web"]` | Source types: `web`, `scholar`, `social`, `edgar` |
| `model` | string | `"auto"` | Model preference |

### `set_cookies`

Set Perplexity cookies at runtime via MCP. Accepts JSON objects or Netscape-format cookie strings.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `cookies_data` | string | **required** | Cookie data — JSON (`{"name":"value"}`) or Netscape format (tab-separated) |
| `session_id` | string | `"default"` | Session ID |

### `list_models`

Lists all available models with their Perplexity internal IDs and use-case descriptions.

### `reset_conversation`

Resets conversation history and starts a fresh context.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `session_id` | string | `"default"` | Session ID |

## Supported Models

| Name | Perplexity ID | Use Case |
|------|---------------|----------|
| `gpt-5` | gpt5 | Balanced, general purpose |
| `gpt-5-thinking` | gpt5_thinking | Complex reasoning, broad sources (~28) |
| `gpt-4o` | gpt4o | Multimodal |
| `gpt-4.5` | gpt45 | General purpose |
| `o3` | o3 | Advanced reasoning, math |
| `o3-pro` | o3pro | Highest reasoning |
| `o3-mini` | o3mini | Fast reasoning, code |
| `o4-mini` | o4mini | Broad sources (~28), balanced |
| `o1` | o1 | Step-by-step reasoning |
| `claude-4.5-sonnet` | claude45sonnet | Detailed analysis, coding |
| `claude-4.5-sonnet-thinking` | claude45sonnetthinking | Complex reasoning |
| `claude-4-opus` | claude40opus | Security-focused |
| `claude-4.1-opus` | claude41opusthinking | Latest Opus, advanced reasoning |
| `grok-4` | grok4 | Latest news, breaking stories |
| `gemini-2.5-pro` | gemini30pro | Multimodal, 1M+ token context |
| `deepseek-r1` | r1 | Price/performance, open source |
| `sonar-pro` | pplx_pro | Fast, concise answers |
| `sonar-deep-research` | o3pro_research | Deep research |
| `perplexity-reasoning` | pplx_reasoning | Balanced, efficient |

Full details: call the `list_models` tool.

## Notes

- **Cookie expiry:** Cookies expire over time. If Perplexity logs you out or returns errors, re-export fresh cookies.
- **Guest mode:** The server works without cookies but will fall back to the `turbo` model only. Authentication significantly expands model availability.
- **Multi-turn conversations:** Supported via `session_id`. Context is maintained server-side through `backend_uuid`, `read_write_token`, and `thread_url_slug`.
- **Reasoning models:** Models like `deepseek-r1`, `o3`, `gpt-5-thinking`, `claude-4.5-sonnet-thinking` emit a separate reasoning/thinking stream that is prepended to the response.
- **Security:** Cookie files in `cookies/` are gitignored by default. Never commit live credentials to version control.