Skip to main content
Glama
Perplexity Web MCP

Perplexity Web MCP

by jacob-bd

Perplexity Web MCP & CLI

PyPI version PyPI downloads Total downloads Python License

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.

WARNING

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

Using uv:

uv tool install perplexity-web-mcp-cli

Using pipx:

pipx install perplexity-web-mcp-cli

Using pip:

pip install perplexity-web-mcp-cli

Note: 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-cli

After 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 doctor

CLI 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_sol
pwm ask "Explain the attention mechanism" -m claude_sonnet

Enable 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 --thinking

Focus 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_cashmere

Output 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-citations

Combine flags for full control:

pwm ask "recent advances in protein folding" -m gemini4_hydrogen -s academic --json

Long 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.pdf

Interactive 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 model

In-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 model

Deep 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 academic
pwm research "NVIDIA competitive landscape" -s finance --json

Model 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 --json

Authentication

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 enabled

Set 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 servers

Models

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 output

The 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 model

MCP 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 tool

For 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 transport

The 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 content

Doctor

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 reference

Models

CLI Name

Provider

Thinking

Notes

auto

Perplexity

No

Auto-selects best model

sonar

Perplexity

No

Sonar 2 (latest in-house; API id experimental)

deep_research

Perplexity

No

Monthly quota, in-depth reports

gpt61_sol

OpenAI

Toggle

GPT-6.1 Sol

gpt6_astra

OpenAI

Toggle

GPT-6 Astra (Max tier required)

gemini4_carbon

Google

Toggle

Gemini 4 Carbon (Max tier required)

gemini4_hydrogen

Google

Toggle

Gemini 4 Hydrogen

claude_sonnet

Anthropic

Toggle

Claude Sonnet 5.5

claude_opus

Anthropic

Toggle

Claude Opus 5.5 (Max tier required)

claude_opus55

Anthropic

Toggle

Alias for Claude Opus 5.5 (Max tier required)

claude_fable52

Anthropic

Toggle

Claude Fable 5.2 (Max tier required)

grok47

xAI

Toggle

Grok 4.7

nemotron

NVIDIA

No

Nemotron 3.5 Super VL (text-only)

glm53

Z.ai

Always

GLM 5.3

kimi_k3

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

web

General web search (default)

News, general questions

academic

Academic papers, journals

Research, citations, scientific topics

social

Reddit, Twitter, forums

Opinions, recommendations, community sentiment

finance

SEC EDGAR filings

Company financials, regulatory filings

all

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_cashmere

MCP 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-code

Or configure manually for any MCP client:

Claude Code CLI:

claude mcp add perplexity pwm-mcp

Claude 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

pplx_query

Flexible: model selection + thinking toggle

pplx_ask

Quick Q&A (auto-selects best model)

pplx_deep_research

In-depth reports with sources

pplx_sonar

Perplexity Sonar 2 (1 Pro Search)

pplx_gpt61_sol / pplx_gpt61_sol_thinking

GPT-6.1 Sol

pplx_gpt6_astra / pplx_gpt6_astra_thinking

GPT-6 Astra (Max tier)

pplx_gemini4_carbon / pplx_gemini4_carbon_thinking

Gemini 4 Carbon (Max tier)

pplx_gemini4_hydrogen / ..._thinking

Gemini 4 Hydrogen

pplx_claude_sonnet / pplx_claude_sonnet_think

Claude Sonnet 5.5

pplx_claude_opus / pplx_claude_opus_think

Claude Opus 5.5 (Max tier)

pplx_claude_fable52 / pplx_claude_fable52_think

Claude Fable 5.2 (Max tier)

pplx_grok47 / pplx_grok47_thinking

Grok 4.7

pplx_nemotron

Nemotron 3.5 Super VL

pplx_glm53

GLM 5.3 (thinking always on)

pplx_kimi_k3

Kimi K3 (thinking always on)

Smart routing (1):

Tool

Description

pplx_smart_query

Quota-aware routing — auto-selects best model based on limits

Council (1):

Tool

Description

pplx_council

Query multiple models in parallel with optional synthesis

Usage, connectors & auth tools (5):

Tool

Description

pplx_usage

Check remaining quotas

pplx_connectors

List connector source IDs

pplx_auth_status

Check authentication status

pplx_auth_request_code

Send verification code to email

pplx_auth_complete

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 api

The 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-terra

Alternatively, launch Claude Code seamlessly using the hack command, which automatically starts the API server and configures the environment for you:

pwm hack claude

OpenAI API

export OPENAI_BASE_URL=http://localhost:8080/v1
export OPENAI_API_KEY=anything

Codex 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 lmstudio

Our 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

perplexity-auto

Best (auto-select)

No

gpt-6.1-sol

GPT-6.1 Sol

Toggle

gpt-6-astra

GPT-6 Astra

Toggle

gemini-4-carbon

Gemini 4 Carbon

Toggle

gemini-4-hydrogen

Gemini 4 Hydrogen

Toggle

claude-sonnet-5-5

Claude Sonnet 5.5

Toggle

claude-opus-5-5

Claude Opus 5.5

Toggle

claude-fable-5-2

Claude Fable 5.2

Toggle

grok-4.7

Grok 4.7

Toggle

glm-5.3 / glm53

GLM 5.3

Always

nemotron-3.5-super-vl

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 login

Non-interactive (for AI agents):

pwm login --email your@email.com
pwm login --email your@email.com --code 123456

Via MCP tools (for AI agents without shell):

  1. Call pplx_auth_request_code(email="your@email.com")

  2. Check email for 6-digit code

  3. 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 login

pwm 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 --version

Diagnose Issues

pwm doctor

This 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-agent

The 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 tools
pplx_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:

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

  2. Check pplx_usage() first. If Subscription is Pro, do not include Max-only models: gpt6_astra, gemini4_carbon, claude_opus, claude_opus55, claude_fable52

  3. Ask the user WHICH models they want in their council and HOW MANY

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

  5. 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:

  1. pplx_list_threads(search_term="topic") — find the thread and its slug

  2. pplx_get_thread(slug) — read the full history for context

  3. 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:

  1. "Did I already research X?" — search before spending a Pro query: pplx_list_threads(search_term="quantum computing")

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

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

    C2.7/5.0

    Scored across 34 tools

    Disambiguation2/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      11
      3
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      MCP 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.
      23
      21
      MIT