Content
# Perplexity Web API MCP Server
<p>
<a href="https://cursor.com/en/install-mcp?name=perplexity-web&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBlcnBsZXhpdHktd2ViLWFwaS1tY3AiXSwiZW52Ijp7IlBFUlBMRVhJVFlfU0VTU0lPTl9UT0tFTiI6IiIsIlBFUlBMRVhJVFlfQ1NSRl9UT0tFTiI6IiJ9fQ==" target="_blank">
<img src="https://custom-icon-badges.demolab.com/badge/Install_in_Cursor-000000?style=for-the-badge&logo=cursor-ai-white" alt="Install in Cursor">
</a>
<a href="https://vscode.dev/redirect/mcp/install?name=perplexity-web&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22perplexity-web-api-mcp%22%5D%2C%22env%22%3A%7B%22PERPLEXITY_SESSION_TOKEN%22%3A%22%22%2C%22PERPLEXITY_CSRF_TOKEN%22%3A%22%22%7D%7D" target="_blank">
<img src="https://custom-icon-badges.demolab.com/badge/Install_in_VS_Code-007ACC?style=for-the-badge&logo=vsc&logoColor=white" alt="Install in VS Code">
</a>
<a href="https://www.npmjs.com/package/perplexity-web-api-mcp" target="_blank">
<img
src="https://img.shields.io/npm/v/perplexity-web-api-mcp?style=for-the-badge&logo=npm&logoColor=white&color=CB3837"
alt="NPM Version" />
</a>
</p>
MCP (Model Context Protocol) server that exposes Perplexity AI search, research, and reasoning capabilities as tools.
## No API Key Required
This MCP server uses your Perplexity account session directly — **no API key needed**.
Perplexity offers a separate [paid API](https://docs.perplexity.ai/guides/pricing) with per-request pricing that is charged independently from your Pro subscription. With this MCP, you don't need to pay for API access — your existing Perplexity subscription (or even a free account) is enough.
Simply extract the session tokens from your browser cookies, and you're ready to use Perplexity search, research, and reasoning in your IDE.
## Tokenless Mode
The server can run **without any authentication tokens**. In this mode:
- Only `perplexity_search` (links only) and `perplexity_ask` (answer with sources) are available — `perplexity_research` and `perplexity_reason` require tokens.
- Both tools use the `turbo` model; `PERPLEXITY_ASK_MODEL` and `PERPLEXITY_REASON_MODEL` cannot be set (the server will throw an error if they are).
- File attachments (`files` parameter) are unavailable — they require tokens.
To use tokenless mode, simply omit `PERPLEXITY_SESSION_TOKEN` and `PERPLEXITY_CSRF_TOKEN` from your configuration.
For full access to all tools and model selection, provide both tokens as described in the [Configuration](#configuration) section below.
## Requirements
### Supported Platforms
- macOS (arm64, x86_64)
- Linux (x86_64, aarch64)
- Windows (x86_64)
## Configuration
### Getting Your Tokens
This server requires a Perplexity AI account. You need to extract two authentication tokens from your browser cookies:
1. Log in to [perplexity.ai](https://www.perplexity.ai) in your browser
2. Open Developer Tools (F12 or right-click → Inspect)
3. Go to Application → Cookies → `https://www.perplexity.ai`
4. Copy the values of:
- `__Secure-next-auth.session-token` → use as `PERPLEXITY_SESSION_TOKEN`
- `next-auth.csrf-token` → use as `PERPLEXITY_CSRF_TOKEN`
### Environment Variables
- `PERPLEXITY_SESSION_TOKEN` (optional): Perplexity session token (`next-auth.session-token` cookie). Required for `perplexity_research`, `perplexity_reason`, and file attachments.
- `PERPLEXITY_CSRF_TOKEN` (optional): Perplexity CSRF token (`next-auth.csrf-token` cookie). Required for `perplexity_research`, `perplexity_reason`, and file attachments.
- `PERPLEXITY_ASK_MODEL` (optional, requires tokens): Model for `perplexity_ask`.
Valid values:
- `turbo` (default for tokenless)
- `pro-auto` (default for authenticated)
- `sonar`
- `gpt-5.4`
- `claude-4.6-sonnet`
- `nemotron-3-super`
- `PERPLEXITY_REASON_MODEL` (optional, requires tokens): Model for `perplexity_reason`.
Valid values:
- `gemini-3.1-pro` (default)
- `gpt-5.4-thinking`
- `claude-4.6-sonnet-thinking`
- `PERPLEXITY_INCOGNITO` (optional, default: `true`): Whether requests should use Perplexity's incognito mode.
Valid values: `true` or `false`
### Claude Code
```bash
claude mcp add perplexity --env PERPLEXITY_SESSION_TOKEN="your-session-token" --env PERPLEXITY_CSRF_TOKEN="your-csrf-token" -- npx -y perplexity-web-api-mcp
```
### Cursor, Claude Desktop & Windsurf
I recommend using the one-click install badge at the top of this README for Cursor.
For manual setup, all these clients use the same `mcpServers` format:
| Client | Config File |
|--------|-------------|
| Cursor | `~/.cursor/mcp.json` |
| Claude Desktop | `claude_desktop_config.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
```json
{
"mcpServers": {
"perplexity": {
"command": "npx",
"args": ["-y", "perplexity-web-api-mcp"],
"env": {
"PERPLEXITY_SESSION_TOKEN": "your-session-token",
"PERPLEXITY_CSRF_TOKEN": "your-csrf-token"
}
}
}
}
```
### Zed
Add following following to `context_servers` in your [settings file](https://zed.dev/docs/configuring-zed.html#settings-files):
```json
{
"context_servers": {
"perplexity": {
"command": "npx",
"args": ["-y", "perplexity-web-api-mcp"],
"env": {
"PERPLEXITY_SESSION_TOKEN": "your-session-token",
"PERPLEXITY_CSRF_TOKEN": "your-csrf-token"
}
}
}
}
```
### VS Code
I recommend using the one-click install badge at the top of this README for VS Code, or for manual setup, add to `.vscode/mcp.json`:
```json
{
"servers": {
"perplexity": {
"type": "stdio",
"command": "npx",
"args": ["-y", "perplexity-web-api-mcp"],
"env": {
"PERPLEXITY_SESSION_TOKEN": "your-session-token",
"PERPLEXITY_CSRF_TOKEN": "your-csrf-token"
}
}
}
}
```
### Codex
```bash
codex mcp add perplexity --env PERPLEXITY_SESSION_TOKEN="your-session-token" --env PERPLEXITY_CSRF_TOKEN="your-csrf-token" -- npx -y perplexity-web-api-mcp
```
### Building from Source
Source build instructions, including optional cargo features, are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
### Other MCP Clients
Most clients can be manually configured to use the `mcpServers` wrapper in their configuration file (like Cursor). If your client doesn't work, check its documentation for the correct wrapper format.
## Docker
A pre-built multi-arch image (`linux/amd64`, `linux/arm64`) is available on Docker Hub:
```bash
docker run -d \
-p 8080:8080 \
-e PERPLEXITY_SESSION_TOKEN="your-session-token" \
-e PERPLEXITY_CSRF_TOKEN="your-csrf-token" \
mishamyrt/perplexity-web-api-mcp
```
The container exposes the MCP server via Streamable HTTP at `http://localhost:8080/mcp`.
The Docker image is built with `--features streamable-http`; local/source builds need the same feature if you want HTTP transport.
Configure your MCP client to connect:
```json
{
"mcpServers": {
"perplexity": {
"url": "http://localhost:8080/mcp"
}
}
}
```
### Environment Variables (Docker-specific)
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `streamable-http` | Transport mode. `stdio` or `streamable-http` (requires the `streamable-http` cargo feature) |
| `MCP_HOST` | `0.0.0.0` | Host address to bind |
| `MCP_PORT` | `8080` | Port to listen on |
The [authentication tokens, model variables, and incognito flag](#configuration) described above work the same way in Docker.
## Available Tools
### `perplexity_search`
Quick web search using the `turbo` model. Returns only links, titles, and snippets — no generated answer.
**Best for:** Finding relevant URLs and sources quickly.
**Parameters:**
- `query` (required): The search query or question
- `sources` (optional): Array of sources — `"web"`, `"scholar"`, `"social"`. Defaults to `["web"]`
- `language` (optional): Language code, e.g., `"en-US"`. Defaults to `"en-US"`
> File attachments are not supported by this tool.
### `perplexity_ask`
Ask Perplexity AI a question and get a comprehensive answer with source citations. By default uses the best model (Pro auto mode) when authentication tokens are provided, or `turbo` in tokenless mode. Can be configured via `PERPLEXITY_ASK_MODEL`.
**Best for:** Getting detailed answers to questions with web context.
**Parameters:** Same as `perplexity_search`, plus:
- `files` (optional, requires tokens): Array of file attachments for document analysis. See [File Attachments](#file-attachments).
### `perplexity_reason`
Advanced reasoning and problem-solving. By default uses Perplexity's `sonar-reasoning` model, but can be configured via `PERPLEXITY_REASON_MODEL`.
**Best for:** Logical problems, complex analysis, decision-making, and tasks requiring step-by-step reasoning.
**Parameters:** Same as `perplexity_ask`.
### `perplexity_research`
Deep, comprehensive research using Perplexity's sonar-deep-research (`pplx_alpha`) model.
**Best for:** Complex topics requiring detailed investigation, comprehensive reports, and in-depth analysis. Provides thorough analysis with citations.
**Parameters:** Same as `perplexity_ask`.
## File Attachments
`perplexity_ask`, `perplexity_research`, and `perplexity_reason` accept an optional `files` parameter for document analysis. **Requires authentication tokens.**
Each entry in the `files` array must have:
- `filename` (required): Filename with extension, e.g. `"report.pdf"` or `"notes.txt"`
- `text` (mutually exclusive with `data`): Plain-text file content. Use for `.txt`, `.md`, `.csv`, `.json`, source code, etc.
- `data` (mutually exclusive with `text`): Base64-encoded binary content. Use for `.pdf`, `.docx`, images, etc.
**Example — plain text:**
```json
{
"query": "Summarise the key points",
"files": [
{
"filename": "notes.txt",
"text": "Meeting notes: Q1 revenue up 12%..."
}
]
}
```
**Example — binary file (PDF):**
```json
{
"query": "What does this contract say about termination?",
"files": [
{
"filename": "contract.pdf",
"data": "JVBERi0xLjQK..."
}
]
}
```
Multiple files can be passed in a single request — they are uploaded to Perplexity's storage in parallel before the query is sent.
## Response Format
`perplexity_search` returns only web results:
```json
{
"web_results": [
{
"name": "Source name",
"url": "https://example.com",
"snippet": "Source snippet"
}
]
}
```
`perplexity_ask`, `perplexity_research`, and `perplexity_reason` return a full response:
```json
{
"answer": "The generated answer text...",
"web_results": [
{
"name": "Source name",
"url": "https://example.com",
"snippet": "Source snippet"
}
],
"follow_up": {
"backend_uuid": "uuid-for-follow-up-queries",
"attachments": []
}
}
```
## License
MIT
