Perplexity Web Wrapper

Perplexity Subscription MCP

Unofficial Python wrapper for Perplexity AI's web interface, providing an MCP (Model Context Protocol) server and Python client for integration with coding agents.

Use your existing Perplexity subscription — no API costs. This wrapper uses your Perplexity web session cookies, so all queries use your existing Pro subscription instead of the paid Perplexity API.

Why This Wrapper?

| Approach | Cost | Rate Limits | |----------|------|-------------| | This wrapper (web session) | $0 (uses your existing subscription) | Your subscription limits | | Perplexity API | $5/1000 requests (sonar), $200/month (pro tier) | API tier limits |

If you already have a Perplexity Pro subscription ($20/month), this wrapper lets you integrate Perplexity into your coding workflow without additional API costs.

Quick Start

No install needed — your MCP config runs the server via uvx automatically.

> Prerequisites: uv and Python 3.10+

1. Get Your Perplexity Cookies

The MCP server authenticates using your browser's Perplexity session cookies. You need to export them once (and re-export when they expire).

Option A: Cookie-Editor Extension (Recommended)

1. Install the Cookie-Editor browser extension (Chrome, Firefox)
2. Go to perplexity.ai and log in to your account
3. Click the Cookie-Editor extension icon
4. Click Export (bottom-left) → copies JSON to clipboard
5. Save the clipboard content to a file:

```bash # Create the config directory mkdir -p ~/.config/perplexity

# Paste your clipboard into this file # macOS: pbpaste > ~/.config/perplexity/cookies.json

# Linux: xclip -selection clipboard -o > ~/.config/perplexity/cookies.json

# Windows (PowerShell): Get-Clipboard | Out-File -Encoding utf8 ~/.config/perplexity/cookies.json

# Or just create the file manually and paste the JSON content ```

This gives you an array format like:

[
  {"domain": ".perplexity.ai", "name": "__Secure-next-auth.session-token", "value": "eyJ...", ...},
  {"domain": ".perplexity.ai", "name": "pplx.visitor-id", "value": "...", ...}
]

Option B: Browser DevTools (Manual)

1. Go to perplexity.ai and log in
2. Open DevTools (F12 or Cmd+Opt+I / Ctrl+Shift+I)
3. Go to Application tab (Chrome) or Storage tab (Firefox)
4. Click Cookies → https://www.perplexity.ai
5. Copy cookie names and values into a JSON file:

{
  "__Secure-next-auth.session-token": "eyJ...",
  "pplx.visitor-id": "...",
  "__cf_bm": "..."
}

Save as ~/.config/perplexity/cookies.json.

> Tip: Export all cookies from perplexity.ai for best results. The essential one is __Secure-next-auth.session-token, but exporting everything avoids issues with missing tokens.

Both formats (array from Cookie-Editor and flat object from manual export) are supported automatically.

2. Add to Your Coding Agent

Pick your agent below. Each config uses uvx to run the server directly from PyPI — no install step needed. Replace YOUR_ABSOLUTE_PATH with your actual home directory path (e.g., /home/user or /Users/yourname).

Claude Code CLI

claude mcp add --transport stdio perplexity --scope user \
  -e PERPLEXITY_COOKIES_PATH=$HOME/.config/perplexity/cookies.json \
  -- uvx --from perplexity-subscription-mcp perplexity-mcp

Verify: claude mcp list · Remove: claude mcp remove perplexity -s user

Augment CLI (Auggie)

auggie mcp add perplexity \
  -e PERPLEXITY_COOKIES_PATH=$HOME/.config/perplexity/cookies.json \
  -- uvx --from perplexity-subscription-mcp perplexity-mcp

Verify: auggie mcp list · Remove: auggie mcp remove perplexity

Cursor IDE

File: ~/.cursor/mcp.json

{
  "mcpServers": {
    "perplexity": {
      "command": "uvx",
      "args": ["--from", "perplexity-subscription-mcp", "perplexity-mcp"],
      "env": {
        "PERPLEXITY_COOKIES_PATH": "YOUR_ABSOLUTE_PATH/.config/perplexity/cookies.json"
      }
    }
  }
}

Windsurf IDE

File: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "perplexity": {
      "command": "uvx",
      "args": ["--from", "perplexity-subscription-mcp", "perplexity-mcp"],
      "env": {
        "PERPLEXITY_COOKIES_PATH": "YOUR_ABSOLUTE_PATH/.config/perplexity/cookies.json"
      }
    }
  }
}

OpenAI Codex CLI

File: ~/.codex/config.toml

[mcp_servers.perplexity]
command = "uvx"
args = ["--from", "perplexity-subscription-mcp", "perplexity-mcp"]

[mcp_servers.perplexity.env]
PERPLEXITY_COOKIES_PATH = "YOUR_ABSOLUTE_PATH/.config/perplexity/cookies.json"

VS Code with Continue Extension

File: .continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["--from", "perplexity-subscription-mcp", "perplexity-mcp"],
          "env": {
            "PERPLEXITY_COOKIES_PATH": "YOUR_ABSOLUTE_PATH/.config/perplexity/cookies.json"
          }
        }
      }
    ]
  }
}

VS Code with Cline Extension

{
  "cline.mcpServers": {
    "perplexity": {
      "command": "uvx",
      "args": ["--from", "perplexity-subscription-mcp", "perplexity-mcp"],
      "env": {
        "PERPLEXITY_COOKIES_PATH": "YOUR_ABSOLUTE_PATH/.config/perplexity/cookies.json"
      }
    }
  }
}

Cookie Location Resolution

If PERPLEXITY_COOKIES_PATH is not set, the server checks these locations in order:

1. PERPLEXITY_COOKIES_PATH env var — explicit file path
2. PERPLEXITY_COOKIES env var — inline JSON string (useful for CI/Docker)
3. ~/.config/perplexity/cookies.json — default user config location
4. ./perplexity_cookies.json — current working directory

Features

Search Modes

| Mode | Description | Pro Subscription Required | |------|-------------|--------------------------| | auto | Quick answers using Perplexity's default model | No | | pro | Enhanced search with model selection | Yes | | reasoning | Deep reasoning with thinking models | Yes | | deep_research | Comprehensive multi-step research | Yes |

Available Models

| Mode | Available Models | |------|-----------------| | auto | Default (turbo) | | pro | Default, sonar, gpt-4.5, gpt-4o, claude 3.7 sonnet, gemini 2.0 flash, grok-2 | | reasoning | Default, r1, o3-mini, claude 3.7 sonnet | | deep_research | Default (alpha) |

Sources

• web — General web search (default)
• scholar — Academic papers and research
• social — Social media content

Additional Features

• Token-efficient answer_only mode: Returns only the answer and backend_uuid, reducing response size
• Follow-up conversations: Continue discussions using backend_uuid from previous responses
• Thread management: List and retrieve past conversation threads
• Incognito mode: Search without saving to history
• File uploads: Attach files to queries (Pro subscription)

MCP Tools Reference

| Tool | Description | Key Parameters | |------|-------------|----------------| | search | Search Perplexity AI | query (required), mode, model, sources, answer_only, language, incognito | | follow_up | Continue a previous conversation | query (required), backend_uuid (required), mode, model, answer_only | | list_threads | List conversation threads | limit, search_term | | get_thread | Get thread details by slug | slug (required) |

Tool Details

search

# Example response with answer_only=True (default)
{
    "answer": "Perplexity AI is an AI-powered search engine...",
    "backend_uuid": "abc-123-def-456"
}

# Example response with answer_only=False
{
    "answer": "Perplexity AI is an AI-powered search engine...",
    "backend_uuid": "abc-123-def-456",
    "sources": ["https://example.com/article1", "https://example.com/article2"],
    "related_queries": ["How does Perplexity AI work?", "Perplexity AI vs ChatGPT"]
}

follow_up

Continue a conversation using the backend_uuid from a previous response.

follow_up(query="Can you elaborate on that?", backend_uuid="abc-123-def-456")

listthreads / getthread

list_threads(limit=10, search_term="python")
get_thread(slug="thread-slug-here")

Agent Instructions (Optional)

To help coding agents use Perplexity MCP efficiently, add these instructions to your agent's rules file:

# Perplexity MCP - Web Research

**Use Perplexity MCP instead of web search. Use fetch/WebFetch only when you need full page content.**

| Tool | Use For |
|------|---------|
| `perplexity.search` | ALL web research - replaces web search |
| `fetch` | Reading full page content in detail when needed |

## Mode Selection

| Research Type | Mode | Use Case |
|--------------|------|----------|
| Quick lookup | `auto` | Simple facts, definitions, quick answers |
| Standard research | `pro` | API docs, library usage, best practices, debugging |
| Deep research | `deep_research` | PRDs, design docs, comprehensive analysis |

## When to Use Each Mode

- **auto**: "What is X?", simple lookups, quick facts
- **pro**: Technical questions, debugging, API research, implementation guidance
- **deep_research**: Creating PRDs, design documents, competitive analysis, comprehensive guides

| Agent | Instructions File | |-------|------------------| | Claude Code | ~/.claude/CLAUDE.md | | Auggie | ~/.augment/rules/perplexity.md | | Cursor | ~/.cursor/CURSOR_INSTRUCTIONS.md | | Codex CLI | ~/.codex/AGENTS.md |

Python Library Usage

Install the package if using as a Python library:

pip install perplexity-subscription-mcp

from perplexity_subscription_mcp import Client
from pathlib import Path
import json

# Load cookies
with open(Path.home() / ".config/perplexity/cookies.json") as f:
    cookies = json.load(f)

# Initialize client
client = Client(cookies)

# Basic search
result = client.search("What is quantum computing?", mode="auto")
print(result)

# Pro search with specific model
result = client.search(
    "Explain transformer architecture",
    mode="pro",
    model="claude 3.7 sonnet",
    sources=["web", "scholar"]
)

# Follow-up query
follow_up_result = client.search(
    "Can you provide code examples?",
    follow_up={
        "backend_uuid": result["backend_uuid"],
        "attachments": []
    }
)

# List threads
threads = client.get_threads(limit=10)

# Get thread details
thread_details = client.get_thread_details_by_slug("thread-slug")

REST API (Optional — for development)

The REST API is not included in the PyPI package. To use it, clone the repo and install with the api extra:

git clone https://github.com/balakumardev/perplexity-web-wrapper.git
cd perplexity-web-wrapper
uv sync --extra api
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

| Endpoint | Method | Description | |----------|--------|-------------| | /api/query_sync | GET | Synchronous search | | /api/query_async | GET | SSE streaming response | | /api/threads | GET | List conversation threads | | /api/threads/{slug} | GET | Get thread details by slug |

Troubleshooting

"No cookies file found"

• Export cookies following the [setup guide](#2-get-your-perplexity-cookies) above
• Verify the file exists: cat ~/.config/perplexity/cookies.json
• Check your MCP config has PERPLEXITY_COOKIES_PATH set correctly

"No remaining pro queries"

• Your Pro subscription may have hit its limit. Use mode="auto" for free searches.

"Invalid model for the selected mode"

• Check the [model compatibility table](#available-models). Some models only work in specific modes.

Connection or authentication errors

• Cookies expire periodically. Re-export from your browser and replace the file.
• Make sure you're logged in to Perplexity when exporting cookies.

Notes

• This is an unofficial project and not affiliated with Perplexity AI
• Respect Perplexity AI's terms of service and rate limits
• Cookie sessions expire periodically — re-export when you get auth errors

License

MIT License. Contributions welcome!

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: balakumardev
• Source: balakumardev/perplexity-web-wrapper
• License: MIT

Install and usage instructions live in the source repository linked above.