Perplexity Web MCP
Perplexity Web MCP exposes MCP tools to query Perplexity AI, manage quota-aware routing, run research, reuse threads/connectors, and authenticate.
Query Perplexity with explicit model/thinking/source focus (
pplx_query) or quick auto Q&A (pplx_ask).Use model-specific tools for Sonar, GPT-5.6 Terra/Sol, Grok, Claude, Gemini, Nemotron, GLM, and Kimi, including thinking variants.
Run deep research synchronously or start async research and poll status.
Use quota-aware
pplx_smart_querywith quick/standard/detailed/research intents.Run
pplx_councilto query multiple models in parallel and optionally synthesize consensus.Continue conversations via
conversation_id, list/search threads, and fetch full thread history.Check usage/quotas, list connector source IDs, and use connectors as
source_focus.Check auth status and complete email/TOTP authentication through MCP tools.
Offers a drop-in replacement for the OpenAI Chat Completions API, allowing clients configured for OpenAI to route requests through Perplexity's models.
Provides a CLI, MCP tools, and API-compatible interface for interacting with Perplexity AI's web interface, enabling queries to premium models, deep research, model council, and multi-turn conversations.
Click on "Deploy 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 Web MCP deep research on agentic AI trends 2026"
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 Web MCP & CLI
MCP server, CLI, and API-compatible interface for Perplexity AI's web interface.
Use your Perplexity Pro/Max subscription to access premium models (GPT-6.1 Sol, GPT-6 Astra, Gemini 4 Carbon, Gemini 4 Hydrogen, Claude Sonnet 5.5, Claude Opus 5.5, Claude Fable 5.2, Grok 4.7, GLM 5.3, Kimi K3, and Nemotron 3.5 Super VL) from the terminal, through MCP tools, or as an API endpoint.
Features
CLI: Query Perplexity models directly from the terminal (
pwm ask,pwm chat,pwm council,pwm research,pwm config)MCP Server: MCP tools for AI agents with citations, rate limit checking, and multi-turn context
API Server: Drop-in Anthropic Messages API and OpenAI Chat Completions API
Premium Models: GPT-6.1 Sol, GPT-6 Astra, Gemini 4 Carbon, Gemini 4 Hydrogen, Claude Sonnet 5.5, Claude Opus 5.5, Claude Fable 5.2, Grok 4.7, GLM 5.3, Kimi K3, and Nemotron 3.5 Super VL
Thinking Mode: Extended thinking support for all compatible models
Deep Research: Full support for Perplexity's Deep Research mode
Multi-Turn Conversations: State-preserved threaded conversations for both MCP and CLI REPL
Model Council: Query multiple models in parallel and get a synthesized consensus
Setup & Skill Management: Auto-configure MCP for Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Cline, Antigravity; install Agent Skills across 9 platforms
Doctor: Diagnose installation, auth, config, rate limits, and skill status
Related MCP server: perplexity-mcp-server
Vibe Coding Alert
Full transparency: this project was built by a non-developer using AI coding assistants. If you're an experienced Python developer, you might look at this codebase and wince. That's okay.
The goal here was to learn — both about building CLI tools in Python and about how modern web applications work under the hood. The code works, but it's very much a learning project released solely for the purpose of research and education, not a polished product.
Unofficial & Unsupported — This project is not affiliated with, endorsed by, or supported by Perplexity AI. It interacts with Perplexity's web interface through unofficial, undocumented methods that may break at any time without notice if Perplexity changes their internal APIs or RPCs. Use at your own risk. The author(s) accept no responsibility for any consequences to your Perplexity account, including but not limited to rate limiting, suspension, or termination. This project is released strictly for educational and research purposes only.
If you know better, teach us. PRs, issues, and architectural advice are all welcome. This is open source specifically because human expertise is irreplaceable.
Installation
From PyPI (recommended)
Using uv:
uv tool install perplexity-web-mcp-cliUsing pipx:
pipx install perplexity-web-mcp-cliUsing pip:
pip install perplexity-web-mcp-cliNote: Requires Python 3.10-3.13.
From source (for development)
git clone https://github.com/jacob-bd/perplexity-web-mcp.git
cd perplexity-web-mcp
uv venv && source .venv/bin/activate
uv pip install -e .Upgrading
pip install --upgrade perplexity-web-mcp-cliAfter upgrading, restart your MCP client (Claude Code, Cursor, etc.) to reload the server.
Quick Start
# 1. Authenticate
pwm login
# 2. Ask a question
pwm ask "What is quantum computing?"
# 3. Chat interactively (keeps one thread across turns)
pwm chat
# 4. Deep research
pwm research "agentic AI trends 2026"
# 5. Check your remaining quotas
pwm usage
# 6. Set up MCP for your AI tools
pwm setup add all # Interactive setup for all detected tools
pwm setup add cursor # Or add individually
# 7. Install the Agent Skill
pwm skill install claude-code
# 8. Diagnose any issues
pwm doctorCLI Reference
Querying
Ask Perplexity a question. By default, Perplexity auto-selects the best model.
pwm ask "What is quantum computing?"Choose a specific model with -m (see Models for the full list):
pwm ask "Compare React and Vue" -m gpt61_solpwm ask "Explain the attention mechanism" -m claude_sonnetEnable extended thinking with -t for deeper reasoning (available on models with Toggle thinking):
pwm ask "Prove that the square root of 2 is irrational" -m claude_sonnet --thinkingFocus on specific sources with -s to control where Perplexity searches:
# Search only academic papers and scholarly articles
pwm ask "transformer architecture improvements 2025" -s academic
# Search only social media (Reddit, Twitter, etc.)
pwm ask "best mechanical keyboard 2026" -s social
# Search SEC EDGAR financial filings
pwm ask "Apple revenue Q4 2025" -s finance
# Search all source types at once
pwm ask "latest AI news" -s all
# Search an account connector source, when your Perplexity account exposes one
pwm connectors list
pwm ask "recent funding for Stripe" -s pitchbook_mcp_cashmereOutput options:
# JSON output (for piping to other tools)
pwm ask "What is Rust?" --json
# Suppress citation URLs (answer text only)
pwm ask "What is Rust?" --no-citationsCombine flags for full control:
pwm ask "recent advances in protein folding" -m gemini4_hydrogen -s academic --jsonLong prompts and attachments:
# Read the prompt from stdin
cat question.txt | pwm ask -
# Or from a UTF-8 file
pwm ask --prompt-file question.txt
# Attach PDFs or images (repeatable)
pwm ask "Summarize the key risks" --file report.pdfInteractive Chat
pwm chat keeps one Perplexity thread across turns, so follow-up questions stay in context. It defaults to the free Sonar model; use -m auto for quota-aware routing, or pin a model with -m.
pwm chat # defaults to Sonar, web sources
pwm chat -m auto # quota-aware model routing
pwm chat -m claude_sonnet --thinking # start with a specific modelIn-session commands: /new starts a fresh thread, /model [NAME] shows or switches the model, /source [NAME] switches the source focus (stays set), /thinking [on|off] toggles extended thinking (stays set), /attach PATH attaches a file to your next message only, and /exit (or /quit, or Ctrl-D) quits.
Saved Defaults
Save a preferred model, thinking mode, and source once; pwm ask, pwm chat, and the MCP pplx_query tool apply them whenever the matching option is omitted. Explicit flags always win.
pwm config set --model grok47 --thinking --source web
pwm config show
pwm config clear # or clear one key: pwm config clear modelDeep Research
Run Perplexity's Deep Research mode for in-depth reports with extensive sources. Uses a separate monthly quota.
pwm research "agentic AI trends 2026"pwm research "climate policy impact on renewable energy" -s academicpwm research "NVIDIA competitive landscape" -s finance --jsonModel Council
Query multiple models in parallel and get a synthesized consensus. Each model costs 1 Pro Search. Default synthesis uses Sonar 2 (also 1 Pro Search).
# Default: GPT-6.1 Sol, Claude Sonnet 5.5, Gemini 4 Hydrogen + Sonar 2 synthesis (4 Pro Searches)
pwm council "What are best practices for microservices?"# Custom model selection
pwm council "Compare Rust and Go" -m gpt61_sol,claude_sonnet# Enable extended thinking for all council models
pwm council "Prove the Pythagorean theorem" --thinking# Skip synthesis, output as JSON
pwm council "React vs Vue" --no-synthesis --jsonAuthentication
pwm login # Interactive login (email + OTP)
pwm login --check # Check if authenticated
pwm login --email user@example.com # Send verification code (non-interactive)
pwm login --email user@example.com --code 123456 # Complete auth with code
pwm login --email user@example.com --code 123456 --totp-code 654321 # Account with TOTP enabledSet PWM_SAVE_TO_LIBRARY=1 to save shared CLI and MCP queries to the Perplexity thread library. Queries are
incognito by default.
Usage & Limits
pwm usage # Check remaining rate limits
pwm usage --refresh # Force-refresh from Perplexity serversModels
pwm models # List the live model catalog (free, no query quota)
pwm models --refresh # Force a fresh fetch from Perplexity
pwm models --json # Machine-readable outputThe catalog mirrors the website model picker with identifiers, tier labels, and "New" flags, and is cached for 24 hours. Any identifier it lists works with pwm ask -m, pwm council -m, and pplx_query(model=...).
Hack
Seamlessly launch external AI tools connected to the Perplexity API server. This automatically starts the local pwm api server in the background, sets the required environment variables, and launches the tool.
pwm hack claude # Launch Claude Code
pwm hack claude -m gpt61_sol # Launch Claude Code with a specific modelMCP Setup
pwm setup list # Show supported tools and MCP configuration status
pwm setup add all # Interactive: detect and configure all tools
pwm setup add claude-code # Add MCP server to Claude Code
pwm setup add cursor # Add MCP server to Cursor
pwm setup add codex # Add MCP server to Codex CLI
pwm setup add gemini # Add MCP server to Gemini CLI
pwm setup add windsurf # Add MCP server to Windsurf
pwm setup add cline # Add MCP server to Cline CLI
pwm setup add antigravity # Add MCP server to Antigravity
pwm setup remove all # Remove from all configured tools
pwm setup remove cursor # Remove MCP server from a toolFor clients that support HTTP/SSE, or when multiple sessions should share one MCP process, run the local daemon:
pwm serve-mcp --transport streamable-http # Start HTTP MCP on 127.0.0.1:8000/mcp
pwm serve-mcp --status # Check daemon status
pwm serve-mcp --stop # Stop the daemon
pwm setup add codex --http # Configure Codex for Streamable HTTP
pwm serve-mcp --transport sse # Start the legacy SSE transportThe HTTP transports bind to loopback by default. Keep the daemon on a loopback address unless you put an authenticated reverse proxy in front of it.
Skill Management
pwm skill list # Show installation status per platform
pwm skill install claude-code # Install skill for Claude Code
pwm skill install cursor --level project # Install at project level
pwm skill uninstall gemini-cli # Remove skill
pwm skill update # Update all outdated skills
pwm skill show # Display skill contentDoctor
pwm doctor # Diagnose installation, auth, config, limits
pwm doctor -v # Verbose (includes security + per-platform skill status)AI Documentation
pwm --ai # Print comprehensive AI-optimized referenceModels
CLI Name | Provider | Thinking | Notes |
| Perplexity | No | Auto-selects best model |
| Perplexity | No | Sonar 2 (latest in-house; API id |
| Perplexity | No | Monthly quota, in-depth reports |
| OpenAI | Toggle | GPT-6.1 Sol |
| OpenAI | Toggle | GPT-6 Astra (Max tier required) |
| Toggle | Gemini 4 Carbon (Max tier required) | |
| Toggle | Gemini 4 Hydrogen | |
| Anthropic | Toggle | Claude Sonnet 5.5 |
| Anthropic | Toggle | Claude Opus 5.5 (Max tier required) |
| Anthropic | Toggle | Alias for Claude Opus 5.5 (Max tier required) |
| Anthropic | Toggle | Claude Fable 5.2 (Max tier required) |
| xAI | Toggle | Grok 4.7 |
| NVIDIA | No | Nemotron 3.5 Super VL (text-only) |
| Z.ai | Always | GLM 5.3 |
| Moonshot | Always | Kimi K3 |
The catalog is server-driven: run pwm models to see the live model list (free, no query quota),
and any identifier it shows can be passed to pwm ask -m <identifier>.
Source Focus
Control where Perplexity searches using -s (CLI) or source_focus (MCP):
Option | Description | Example Use Case |
| General web search (default) | News, general questions |
| Academic papers, journals | Research, citations, scientific topics |
| Reddit, Twitter, forums | Opinions, recommendations, community sentiment |
| SEC EDGAR filings | Company financials, regulatory filings |
| Web + Academic + Social combined | Broad coverage across all sources |
Account Connector Sources
Accounts with Perplexity connectors may expose additional source IDs such as pitchbook_mcp_cashmere or cbinsights_mcp_cashmere. List IDs before using them:
pwm connectors list
pwm ask "recent funding for Stripe" -s pitchbook_mcp_cashmereMCP clients should call pplx_connectors() first, then pass the returned ID as source_focus.
Connector access inherits the authenticated Perplexity account's permissions and may expose private organization or cloud data to whichever local agent can call this tool. Unknown and unreported connector values fail instead of falling back to web search. Administrators can set PWM_CONNECTORS_ENABLED=0 to disable connector queries or set PWM_CONNECTOR_ALLOWLIST to a comma-separated list of exact connector IDs. When these variables are unset, reported connectors remain available for backward compatibility. See Account Connector Sources for the full trust-boundary guidance.
MCP Server
Setup
The easiest way to configure MCP:
pwm setup add claude-codeOr configure manually for any MCP client:
Claude Code CLI:
claude mcp add perplexity pwm-mcpClaude Desktop — Download the .mcpb extension from the latest release and open it with Claude Desktop. Or configure manually:
{
"mcpServers": {
"perplexity": {
"command": "pwm-mcp"
}
}
}Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"perplexity": {
"command": "pwm-mcp"
}
}
}Available MCP Tools
Query tools:
Tool | Description |
| Flexible: model selection + thinking toggle |
| Quick Q&A (auto-selects best model) |
| In-depth reports with sources |
| Perplexity Sonar 2 (1 Pro Search) |
| GPT-6.1 Sol |
| GPT-6 Astra (Max tier) |
| Gemini 4 Carbon (Max tier) |
| Gemini 4 Hydrogen |
| Claude Sonnet 5.5 |
| Claude Opus 5.5 (Max tier) |
| Claude Fable 5.2 (Max tier) |
| Grok 4.7 |
| Nemotron 3.5 Super VL |
| GLM 5.3 (thinking always on) |
| Kimi K3 (thinking always on) |
Smart routing (1):
Tool | Description |
| Quota-aware routing — auto-selects best model based on limits |
Council (1):
Tool | Description |
| Query multiple models in parallel with optional synthesis |
Usage, connectors & auth tools (5):
Tool | Description |
| Check remaining quotas |
| List connector source IDs |
| Check authentication status |
| Send verification code to email |
| Complete email and TOTP authentication |
All query tools support source_focus: none, web, academic, social, finance, all, or a connector source ID returned by pplx_connectors().
API Server
Use Perplexity models through Anthropic or OpenAI compatible API endpoints.
Start the server
pwm apiThe server binds to 127.0.0.1 by default. A non-loopback --host or HOST
value is rejected unless PWM_API_KEY (or the legacy ANTHROPIC_API_KEY)
contains a non-empty secret. Remote use should also be protected by a trusted
TLS reverse proxy and firewall rules because the built-in server serves plain
HTTP. Clients may send the configured secret as x-api-key or
Authorization: Bearer <secret>.
When an API key is configured, the same authentication applies to every API
endpoint, including the /v1/responses WebSocket route. The server rejects
unauthenticated WebSocket connections before accepting the connection.
Anthropic API (Claude Code)
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=perplexity
claude --model gpt-5.6-terraAlternatively, launch Claude Code seamlessly using the hack command, which automatically starts the API server and configures the environment for you:
pwm hack claudeOpenAI API
export OPENAI_BASE_URL=http://localhost:8080/v1
export OPENAI_API_KEY=anythingCodex CLI Integration
Codex CLI performs strict client-side model validation. By default, it will reject any model name that isn't a recognized OpenAI ChatGPT account model (e.g., rejecting sonar).
To bypass this client-side block and use arbitrary Perplexity models natively, start Codex with the --local-provider lmstudio flag (or --oss). This instructs Codex to treat the backend as a local proxy:
export OPENAI_API_BASE=http://localhost:8080/v1
export OPENAI_API_KEY=dummy
codex -m sonar --local-provider lmstudioOur server's MODEL_MAP will seamlessly intercept sonar (or any other mapped names like gemini-4-hydrogen, nemotron, glm-5.3, claude-sonnet-5-5) and correctly route it to Perplexity's API. You can also create an alias in your shell to make this easier: alias codex-pplx="codex --local-provider lmstudio".
API Model Names
API Name | Perplexity Model | Thinking |
| Best (auto-select) | No |
| GPT-6.1 Sol | Toggle |
| GPT-6 Astra | Toggle |
| Gemini 4 Carbon | Toggle |
| Gemini 4 Hydrogen | Toggle |
| Claude Sonnet 5.5 | Toggle |
| Claude Opus 5.5 | Toggle |
| Claude Fable 5.2 | Toggle |
| Grok 4.7 | Toggle |
| GLM 5.3 | Always |
| Nemotron 3.5 Super VL | No |
Legacy aliases (claude-3-5-sonnet, claude-3-opus) are supported for compatibility.
Python API
from perplexity_web_mcp import Perplexity, ConversationConfig, Models
client = Perplexity(session_token="your_token")
conversation = client.create_conversation(
ConversationConfig(model=Models.CLAUDE_45_SONNET)
)
conversation.ask("What is quantum computing?")
print(conversation.answer)
for result in conversation.search_results:
print(f"Source: {result.url}")
# Follow-up (context preserved)
conversation.ask("Explain it simpler")
print(conversation.answer)Subscription Tiers & Rate Limits
Tier | Cost | Pro Search | Deep Research | Labs |
Free | $0 | 3/day | 1/month | No |
Pro | $20/mo | Weekly pool | Monthly pool | Monthly pool |
Max | $200/mo | Weekly pool | Monthly pool | Monthly pool |
The MCP server checks quotas before each query. Use pwm usage or pplx_usage to check your limits.
Troubleshooting
Authentication Errors (403)
Session tokens are long-lived, but Perplexity can invalidate them at any time. Re-authenticate when expired or when pwm usage reports a rejected session:
pwm loginNon-interactive (for AI agents):
pwm login --email your@email.compwm login --email your@email.com --code 123456Via MCP tools (for AI agents without shell):
Call
pplx_auth_request_code(email="your@email.com")Check email for 6-digit code
Call
pplx_auth_complete(email="your@email.com", code="123456")
If the tool returns TOTP_REQUIRED, call it again with
pplx_auth_complete(email="your@email.com", totp_code="654321").
Session Expired or Zeroed Limits
If quotas suddenly show all zeros or thread listings come back empty, the saved session may have been invalidated. pwm usage detects this case and prints SESSION EXPIRED with a re-login hint instead of anonymous zeros:
pwm loginpwm doctor also verifies the stored session and reports token invalid or expired when a fresh login is needed.
Blank or Truncated Answers
Perplexity can return answer chunks without the older text field. If pwm ask returns No answer received or only part of the answer, upgrade to the latest patch release:
uv tool upgrade perplexity-web-mcp-cli
pwm --versionDiagnose Issues
pwm doctorThis checks installation, authentication, rate limits, MCP configuration, and skill installation -- with fix suggestions for every issue found.
Rate Limiting
CLI/MCP: Auto-checks quotas before each query, blocks if exhausted
API server: Enforces 5-second minimum between requests
Agent Skill
This project includes a portable Agent Skill (SKILL.md) that teaches AI agents how to use the CLI and MCP tools. Install it for your platform:
pwm skill install all # Install for all detected tools
pwm skill install claude-code # Or install individually
pwm skill install cursor
pwm skill install codex
pwm skill install gemini-cli
pwm skill install antigravity
pwm skill install cline
pwm skill install opencode
pwm skill install openclaw
pwm skill install alef-agentThe skill follows Anthropic's Agent Skills open standard and works across any compliant AI platform.
Credits
Originally forked from perplexity-webui-scraper by henrique-coder.
Support
If Perplexity Web MCP saves you time or money, you can help cover the AI bills that go into building and testing it. Any support is hugely appreciated. 🙏
License
MIT
Available Tools
34 toolspplx_askA
Quick Q&A with auto model. COSTS 1 PRO SEARCH QUERY. Prefer pplx_smart_query(intent='quick') for simple lookups (Sonar 2 first).
An omitted source_focus falls back to your saved default (set with pwm config), then web.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_auth_completeA
Complete Perplexity authentication with the verification code.
Use the 6-digit code received via email after calling pplx_auth_request_code. On success, the session token is saved and all pplx_* tools will work.
Args: email: Your Perplexity account email (same as used in pplx_auth_request_code) code: The 6-digit verification code from your email totp_code: The 6-digit authenticator code when TOTP is enabled
Returns: Status message with authentication result and subscription tier
Inputs: email (required), code, totp_code. Returns: result
pplx_auth_request_codeA
Request a verification code for Perplexity authentication.
Sends a 6-digit verification code to the provided email address. After calling this, check the email inbox and use pplx_auth_complete with the code to finish authentication.
Args: email: Your Perplexity account email address
Returns: Status message indicating if the code was sent successfully
Inputs: email (required). Returns: result
pplx_auth_statusA
Check if Perplexity is authenticated.
Returns the current authentication status and subscription tier if authenticated. Use this to check if re-authentication is needed before making queries.
Inputs: no named parameters. Returns: result
pplx_claude_fable52C
Claude Fable 5.2 — Anthropic's most capable model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_claude_fable52_thinkC
Claude Fable 5.2 Thinking — Anthropic's most capable model with extended thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_claude_opusC
Claude Opus 5.5 — Anthropic's latest model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_claude_opus_thinkC
Claude Opus 5.5 Thinking — Anthropic's latest model with extended thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_claude_sonnetC
Claude Sonnet 5.5 — Anthropic's fast model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_claude_sonnet_thinkD
Claude Sonnet 5.5 Thinking — Anthropic's newest reasoning model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_connectorsA
List account connector source IDs that can be passed as source_focus.
Returns source IDs from the Perplexity rate-limit API. Use these IDs as source_focus values, for example source_focus="pitchbook_mcp_cashmere".
Inputs: refresh. Returns: result
pplx_councilA
Model Council — query multiple models in parallel, get synthesized consensus.
IMPORTANT — BEFORE calling this tool, you MUST:
Tell the user the available models: sonar, gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, gemini_pro, claude_sonnet, claude_opus, claude_opus55, claude_fable52, grok47, nemotron, glm53, kimi_k3
Check pplx_usage() first. If Subscription is Pro, do not include Max-only models: gpt6_astra, gemini4_carbon, claude_opus, claude_opus55, claude_fable52
Ask the user WHICH models they want in their council and HOW MANY
Inform them of the cost: each council model = 1 Pro Search query, plus synthesis (default chairman sonar = Sonar 2 pass — still counts as a normal query toward limits)
Get explicit confirmation before executing
Default council: GPT-6.1 Sol, Claude Sonnet 5.5, Gemini 4 Hydrogen (Pro-compatible, 3 diverse providers).
Args: query: The question to ask all council models source_focus: Source type for all models (none/web/academic/social/finance/all or connector source ID) models: Comma-separated model names to use as council members. Available: sonar, gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, gemini_pro, claude_sonnet, claude_opus, claude_opus55, claude_fable52, grok47, nemotron, glm53, kimi_k3. Default: "gpt61_sol,claude_sonnet,gemini4_hydrogen" (3 models + synthesis = 4 Pro Searches) Max-only: gpt6_astra, gemini4_carbon, claude_opus, claude_opus55, claude_fable52. Exclude these when pplx_usage shows a Pro subscription. synthesize: Whether to synthesize a consensus from all responses. Set false to get only individual responses (saves 1 Sonar 2 call). thinking: Enable extended thinking for council models (gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, claude_sonnet, claude_opus, claude_opus55, claude_fable52, and grok47 support toggle; glm53 and kimi_k3 are always thinking). chairman: Model to use for synthesis (default: "sonar" / Sonar 2). Non-sonar chairmen cost 1 extra Pro Search query.
Inputs: query (required), models, chairman, thinking, +2 more. Returns: result
pplx_deep_researchB
Deep Research — in-depth reports. COSTS 1 DEEP RESEARCH QUERY (limited monthly pool, typically 5-10 total). Only use when the user explicitly requests deep research.
Inputs: query (required), source_focus. Returns: result
pplx_deep_research_startA
Start a deep research task asynchronously. COSTS 1 DEEP RESEARCH QUERY.
Use this instead of pplx_deep_research for complex queries to avoid connection timeouts. Returns a task_id immediately. Poll pplx_research_status with the task_id to get the result.
Inputs: query (required), source_focus. Returns: result
pplx_gemini4_carbonC
Gemini 4 Carbon — Google's most powerful model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_gemini4_carbon_thinkingC
Gemini 4 Carbon Thinking — Google's most powerful model with thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_gemini4_hydrogenC
Gemini 4 Hydrogen — Google's latest model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_gemini4_hydrogen_thinkingD
Gemini 4 Hydrogen Thinking — Google's latest model with thinking. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_get_threadA
Fetch the full conversation history for a Perplexity thread. FREE — zero quota cost.
Returns the complete Q&A turns, sources, and related queries for any past thread. Get the slug from pplx_list_threads, or from the [Conversation ID: ...] footer returned by any pplx_* query tool.
RESUME PATTERN — to continue a past conversation:
pplx_list_threads(search_term="topic") — find the thread and its slug
pplx_get_thread(slug) — read the full history for context
pplx_smart_query("follow-up question", conversation_id=slug) — continue it
Args: slug: Thread UUID / slug. Obtain from pplx_list_threads or a previous [Conversation ID: ...] response footer.
Inputs: slug (required). Returns: result
pplx_glm53C
GLM 5.3 — Z.ai's newest model with thinking always enabled. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_gpt61_solD
GPT-6.1 Sol — OpenAI's versatile model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_gpt61_sol_thinkingC
GPT-6.1 Sol Thinking — OpenAI's versatile model with thinking. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_gpt6_astraC
GPT-6 Astra — OpenAI's most capable model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_gpt6_astra_thinkingC
GPT-6 Astra Thinking — OpenAI's most capable model with thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_grok47C
Grok 4.7 — xAI's most advanced model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_grok47_thinkingC
Grok 4.7 Thinking — xAI's most advanced model with thinking. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_kimi_k3C
Kimi K3 — Moonshot's newest model with thinking always enabled. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_list_threadsA
Browse your Perplexity thread library. FREE — zero quota cost.
Returns a paginated list of your past Perplexity conversations with their slugs, titles, models used, and answer previews.
PRIMARY USE CASES:
"Did I already research X?" — search before spending a Pro query: pplx_list_threads(search_term="quantum computing")
Find a conversation to resume — get its slug, then pass it as conversation_id to any pplx_* query tool to continue right where it left off.
Retrieve full history — call pplx_get_thread(slug) with any slug from this list.
Args: limit: Max threads to return (default 20, max 100). offset: Skip this many threads — use for pagination (e.g. offset=20 for page 2). search_term: Optional keyword to filter threads by title or content.
Inputs: limit, offset, search_term. Returns: result
pplx_nemotronC
Nemotron 3.5 Super VL — NVIDIA's newest Nemotron model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_queryA
Query Perplexity AI with explicit model selection. COSTS 1 PRO SEARCH QUERY per call.
Prefer pplx_smart_query for automatic quota-aware routing. Use this only when
you need a specific model or thinking mode. Omitted model, thinking, and
source_focus fall back to saved defaults (set with pwm config in the CLI),
then to auto/web/off.
Args: query: The question to ask model: Model to use - auto, sonar, deep_research, gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, gemini_pro, claude_sonnet, claude_opus, claude_opus55, claude_fable52, grok47, nemotron, glm53, kimi_k3 (any live catalog identifier is also accepted). An unknown name returns an error with close-match suggestions. thinking: Enable extended thinking mode (available for gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, claude_sonnet, claude_opus, claude_opus55, claude_fable52, grok47; always on for glm53 and kimi_k3) source_focus: Source type - none (model only, no search), web, academic, social, finance, all, or connector source ID from pplx_connectors() files: Local file paths to attach (PDF or image). On Free-tier accounts an attachment can make the query count as a Pro Search.
Inputs: query (required), files, model, thinking, +2 more. Returns: result
pplx_research_statusA
Check the status of an asynchronous deep research task.
Returns 'in_progress' if the task is still running, the final research report if completed, or an error message if it failed.
Inputs: task_id (required). Returns: result
pplx_smart_queryA
RECOMMENDED DEFAULT TOOL. Quota-aware query — checks limits and picks the best model automatically.
USE THIS FOR EVERY QUERY unless the user explicitly requests a specific model. Default to intent='quick' for most lookups — it routes to Sonar 2 when appropriate. Only escalate intent when the question genuinely requires it.
Intent guide (choose the LOWEST sufficient level):
quick: Facts, definitions, simple lookups, 'what is X' → Sonar 2 (check pplx_usage)
standard: How-to, comparisons, explanations needing web sources → 1 Pro Search
detailed: Complex multi-source analysis, technical deep-dives → 1 Pro Search (premium model)
research: Comprehensive report → 1 Deep Research (scarce monthly quota, user must request)
Response includes a metadata block showing the model used, routing reason, and current quota snapshot.
Args:
query: The question to ask
intent: Query complexity — quick (default for most), standard, detailed, research
source_focus: Source type — none (model only, no search), web, academic,
social, finance, all, or connector source ID from pplx_connectors().
Omit it to use your saved default (set with pwm config), then web.
conversation_id: Pass the ID from a previous response to continue that thread
files: Local file paths to attach (PDF or image). On Free-tier accounts an
attachment can make the query count as a Pro Search.
Inputs: query (required), files, intent, source_focus, +1 more. Returns: result
pplx_sonarC
Sonar 2 — Perplexity's latest in-house model. Subject to your plan and Perplexity usage counters (see pplx_usage).
Inputs: query (required), source_focus, conversation_id. Returns: result
pplx_usageA
Check current Perplexity usage limits and remaining quotas.
CALL THIS AT THE START OF EVERY SESSION before making any queries. Shows remaining Pro Search (weekly), Deep Research (monthly), and other quotas. Use the results to decide whether to conserve Pro quota (e.g. quick intent before premium models).
Args: refresh: Force refresh from Perplexity (ignores cache). Default False.
Inputs: refresh. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 34 tools
Four general query tools (pplx_query, pplx_ask, pplx_smart_query, pplx_sonar) overlap heavily, and the 19 per-model wrappers (plus their _thinking/_think variants) duplicate exactly what pplx_query's model argument already does. Descriptions do nudge toward pplx_smart_query as the default, which mitigates but does not resolve the misselection risk.
All tools share the pplx_ prefix and snake_case, which is readable, but the thinking suffix is inconsistent: pplx_gpt61_sol_thinking vs pplx_claude_sonnet_think / pplx_claude_opus_think / pplx_grok47_thinking. The naming also bakes model names into tool names, which is inherently unstable.
34 tools is well beyond what this domain needs; roughly 19 of them are thin per-model wrappers that could be a single parameterized tool. The genuinely distinct capabilities (query, deep research, threads, auth, usage) number about a dozen.
Coverage is strong: querying, async deep research with status polling, thread browsing/resumption, connector discovery, usage inspection, and a full auth flow. Minor gaps like thread deletion/renaming or a non-synthesis council-only path exist but are workable.
Maintenance
Related MCP Connectors
Real-time web search, reasoning, and research through Perplexity's API
Official Exa MCP for web search, content fetching, and multi-step research.
Enable AI assistants to perform web searches using Perplexity's Sonar Pro.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Related MCP Servers
- AlicenseAqualityBmaintenanceA comprehensive MCP server that provides intelligent access to Perplexity AI's search and reasoning models with automatic model selection, conversation management, and project-aware storage. Supports real-time search, deep research, chat sessions, and async operations for complex queries.113MIT
- FlicenseBqualityDmaintenanceEnables interaction with Perplexity AI through MCP tools for chatting, searching, and retrieving documentation.51-
- AlicenseNot gradedqualityCmaintenanceMCP server that queries Perplexity Pro via WebUI session token, providing model-specific tools for search and deep research.163 npm5MIT
- AlicenseCqualityDmaintenanceMCP server providing 22 tools to query Perplexity AI's premium models (GPT-5.4, Claude 4.7 Opus, etc.) with citations, source discovery, and rate limit checking for AI agents.2321MIT