Perplexity MCP
Provides search capabilities using Perplexity AI's web interface, enabling AI agents to query Perplexity with various modes (auto, pro, reasoning, deep_research) and models, using the user's existing Perplexity Pro subscription.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Perplexity MCPsearch the web for latest AI breakthroughs in 2024"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
Option A: Cookie-Editor Extension (Recommended)
Install the Cookie-Editor browser extension (Chrome, Firefox)
Go to perplexity.ai and log in to your account
Click the Cookie-Editor extension icon
Click Export (bottom-left) → copies JSON to clipboard
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)
Go to perplexity.ai and log in
Open DevTools (
F12orCmd+Opt+I/Ctrl+Shift+I)Go to Application tab (Chrome) or Storage tab (Firefox)
Click Cookies →
https://www.perplexity.aiCopy 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-mcpVerify: 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-mcpVerify: 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:
PERPLEXITY_COOKIES_PATHenv var — explicit file pathPERPLEXITY_COOKIESenv var — inline JSON string (useful for CI/Docker)~/.config/perplexity/cookies.json— default user config location./perplexity_cookies.json— current working directory
Features
Search Modes
Mode | Description | Pro Subscription Required |
| Quick answers using Perplexity's default model | No |
| Enhanced search with model selection | Yes |
| Deep reasoning with thinking models | Yes |
| Comprehensive multi-step research | Yes |
Available Models
Mode | Available Models |
| Default (turbo) |
| Default, |
| Default, |
| Default (alpha) |
Sources
web— General web search (default)scholar— Academic papers and researchsocial— Social media content
Additional Features
Token-efficient
answer_onlymode: Returns only the answer andbackend_uuid, reducing response sizeFollow-up conversations: Continue discussions using
backend_uuidfrom previous responsesThread 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 Perplexity AI |
|
| Continue a previous conversation |
|
| List conversation threads |
|
| Get thread details by slug |
|
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")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 guidesAgent | Instructions File |
Claude Code |
|
Auggie |
|
Cursor |
|
Codex CLI |
|
Python Library Usage
Install the package if using as a Python library:
pip install perplexity-subscription-mcpfrom 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 8000Endpoint | Method | Description |
| GET | Synchronous search |
| GET | SSE streaming response |
| GET | List conversation threads |
| 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.jsonCheck your MCP config has
PERPLEXITY_COOKIES_PATHset 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. 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!
Available Tools
4 toolsfollow_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'.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| backend_uuid | Yes | ||
| mode | No | auto | |
| model | No | ||
| answer_only | No |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| search_term | No |
TDQS
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.
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.
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.
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.
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.
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.
searchB
Search Perplexity AI with the given query.
Args: query: The search query string mode: Search mode - 'auto', 'pro', 'reasoning', or 'deep_research' model: Specific model to use (depends on mode): - auto: None - pro: None, 'sonar', 'gpt-4.5', 'gpt-4o', 'claude 3.7 sonnet', 'gemini 2.0 flash', 'grok-2' - reasoning: None, 'r1', 'o3-mini', 'claude 3.7 sonnet' - deep_research: None sources: List of sources to use - 'web', 'scholar', 'social' answer_only: If True, return only answer and backend_uuid. If False, also include sources and related_queries. language: Language code (ISO 639, e.g., 'en-US') incognito: Whether to enable incognito mode
Returns: Dictionary with 'answer' and 'backend_uuid'. If answer_only=False, also includes 'sources' and 'related_queries'.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| mode | No | auto | |
| model | No | ||
| sources | No | ||
| answer_only | No | ||
| language | No | en-US | |
| incognito | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It details parameters and return values but does not mention side effects, idempotency, rate limits, or permissions. The tool likely performs a read-only search, but this is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into Args and Returns sections, with each parameter explained concisely. It could be slightly more terse, especially the model-per-mode lists, but it remains clear and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 7 parameters and no output schema or annotations, the description covers all parameters and describes the return structure. It lacks details about error handling or pagination, but it sufficiently informs usage for typical queries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It does so by explaining modes, model dependencies, sources, answer_only behavior, language, and incognito mode, adding significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Perplexity AI with a given query. It lists all parameters but does not explicitly distinguish from sibling tools like follow_up or get_thread, which could cause ambiguity when deciding which tool to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for performing searches but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. The sibling tools handle follow-ups and threads, so there is some implicit differentiation.
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.
4 tool updates
v0.1.2- First observed
follow_up - First observed
get_thread - First observed
list_threads - First observed
search
TDQS
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.
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.
With 4 tools, the server is well-scoped for a conversational search assistant, covering essential operations without being too sparse or overwhelming.
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
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
Real-time web search, reasoning, and research through Perplexity's API
Enable AI assistants to perform web searches using Perplexity's Sonar Pro.
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceInterfaces with the Perplexity AI API to provide advanced question answering capabilities through the standardized Model Context Protocol, supporting multiple Perplexity models.-
- AlicenseNot gradedqualityDmaintenanceProvides 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.132MIT
- AlicenseBqualityAmaintenanceEnables 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.30180MIT
- AlicenseAqualityCmaintenanceProvides AI-powered research capabilities through Perplexity's web interface, enabling web search, deep research, chat, and documentation retrieval without API keys.8GPL 3.0
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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