Skip to main content
Glama
balakumardev

Perplexity MCP

by balakumardev

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.

Related MCP server: MCP Perplexity Server

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).

  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:

    # 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 Cookieshttps://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"
      }
    }
  }
}

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

# 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")

list_threads / get_thread

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 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"

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!

Available Tools

4 tools
follow_upA

Send a follow-up query to continue a previous conversation.

Args: query: The follow-up query string backend_uuid: The backend_uuid from the previous response mode: Search mode - 'auto', 'pro', 'reasoning', or 'deep_research' model: Specific model to use (see search tool for options) answer_only: If True, return only answer and backend_uuid. If False, also include sources and related_queries.

Returns: Dictionary with 'answer' and 'backend_uuid'. If answer_only=False, also includes 'sources' and 'related_queries'.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
backend_uuidYes
modeNoauto
modelNo
answer_onlyNo

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so description carries burden. It describes input/output but does not disclose side effects, permissions, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, including param docs and return info, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It explains return values despite no output schema, but lacks usage guidelines and behavioral transparency, leaving gaps for a tool with multiple parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description explains each parameter (query, backend_uuid, mode, model, answer_only) with context beyond their types and titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it sends a follow-up query to continue a conversation, distinguishing it from sibling tools like search (new queries) and get_thread (retrieving threads).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have a backend_uuid from a previous response, but does not explicitly state when to use alternatives or provide exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_threadA

Get details of a specific thread by its slug.

Args: slug: The thread slug (identifier from thread URL or list_threads)

Returns: Dictionary containing thread details including all messages

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It indicates the tool is a read operation (get) and returns thread details with messages, but does not explicitly state idempotency, side effects, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: a single introductory line followed by clearly separated Args and Returns sections. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter. The description explains the return value as a dictionary with thread details and messages. It covers the essentials, though it could mention error handling (e.g., if slug not found).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the tool description explains the slug parameter's origin ('identifier from thread URL or list_threads'), adding meaning beyond the schema's bare type and title.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Get), the resource (details of a specific thread), and the identifier (slug). It distinguishes itself from sibling tools like list_threads (which lists threads) and search (which searches).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that this tool is used when a slug is known, but it does not explicitly provide when-to-use or when-not-to-use guidance, nor does it mention alternative tools like list_threads or search for different use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_threadsC

List conversation threads from Perplexity AI.

Args: limit: Maximum number of threads to return (default 10) search_term: Optional search term to filter threads

Returns: Dictionary containing list of threads with their metadata

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
search_termNo

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description lacks behavioral details like pagination, rate limits, or side effects. The agent gains no insight beyond the basic listing operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured into clear Args/Returns sections and is reasonably concise. It could be more succinct by integrating the sections into a flowing sentence, but overall it is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list operation with two optional parameters, the description covers the core purpose. However, it lacks details on pagination behavior, response format specifics (despite mentioning metadata), and differentiation from get_thread, making it minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds minimal semantics: limit is described as 'Maximum number of threads' and search_term as 'Optional search term'. This partially compensates for missing schema descriptions but does not explain formats or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List conversation threads from Perplexity AI,' specifying the verb 'list' and resource 'threads'. However, it does not differentiate from sibling tools like get_thread or search, which could cause confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as get_thread (single thread) or search. The agent receives no context on appropriate use cases or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.2
    • First observedfollow_up
    • First observedget_thread
    • First observedlist_threads
    • First observedsearch

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: search for initial queries, follow_up for continuing conversations, list_threads for browsing threads, and get_thread for retrieving full thread details. There is no functional overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (search, follow_up, list_threads, get_thread), making the set predictable and easy to understand.

Tool Count5/5

With 4 tools, the server is well-scoped for a conversational search assistant, covering essential operations without being too sparse or overwhelming.

Completeness4/5

The tool set covers the core workflow (search, follow-up, list threads, view details) but lacks delete functionality for threads, which is a minor gap.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Provides AI-powered search, research, and reasoning capabilities through integration with Perplexity.ai, offering three specialized tools: general conversational AI, deep research with citations, and advanced reasoning.
    13
    2
    MIT
  • A
    license
    B
    quality
    A
    maintenance
    Enables AI agents and users to query Perplexity AI's premium models (GPT-5.4, Claude 4.6 Opus, Gemini 3.1 Pro, etc.) via MCP tools, CLI, or API, with support for deep research, model council, and multi-turn conversations.
    30
    180
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    Provides AI-powered research capabilities through Perplexity's web interface, enabling web search, deep research, chat, and documentation retrieval without API keys.
    8
    GPL 3.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/balakumardev/perplexity-web-wrapper'

If you have feedback or need assistance with the MCP directory API, please join our Discord server