Back to search
perplexity-web-api-mcp
MCP serverGitHub
π Perplexity AI MCP without API key
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/mishamyrt--perplexity-web-api-mcp)HTML
<a href="/listings/mishamyrt--perplexity-web-api-mcp"><img src="/api/listings/mishamyrt--perplexity-web-api-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 322 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.