Perplexity Web MCP
Provides access to Perplexity AI's web interface, allowing queries to premium models (GPT-5.4, GPT-5.5, Claude 4.7 Opus, Claude 4.6 Sonnet, Gemini 3.1 Pro, Nemotron 3 Super, Kimi K2.6, Sonar 2) with extended thinking, deep research, multi-model councils, and source focus options through CLI, MCP tools, and API endpoints.
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 Research the history of the Roman Empire with citations."
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-5.4, GPT-5.5, Claude 4.7 Opus, Claude 4.6 Sonnet, Gemini 3.1 Pro, Nemotron 3 Super, Kimi K2.6) from the terminal, through MCP tools, or as an API endpoint.
Features
CLI: Query Perplexity models directly from the terminal (
pwm ask,pwm council,pwm research)MCP Server: 22 MCP tools for AI agents with citations, source discovery, and rate limit checking
API Server: Drop-in Anthropic Messages API and OpenAI Chat Completions API
8 Models: GPT-5.4, GPT-5.5, Claude 4.7 Opus, Claude 4.6 Sonnet, Gemini 3.1 Pro, Nemotron 3 Super, Kimi K2.6, Sonar 2
Thinking Mode: Extended thinking support for all compatible models
Deep Research: Full support for Perplexity's Deep Research mode
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. Deep research
pwm research "agentic AI trends 2026"
# 4. Check your remaining quotas
pwm usage
# 5. Set up MCP for your AI tools
pwm setup add all # Interactive setup for all detected tools
pwm setup add cursor # Or add individually
# 6. Install the Agent Skill
pwm skill install claude-code
# 7. 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 gpt54pwm 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 allOutput 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 gemini_pro -s academic --jsonDeep 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-5.4, Claude Opus, Gemini Pro + Sonar 2 synthesis (4 Pro Searches)
pwm council "What are best practices for microservices?"# Custom model selection
pwm council "Compare Rust and Go" -m gpt54,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 codeUsage & Limits
pwm usage # Check remaining rate limits
pwm usage --refresh # Force-refresh from Perplexity serversHack
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 gpt54 # 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 toolSkill 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-5.4 |
| OpenAI | Toggle | GPT-5.5 (Max tier required) |
| Anthropic | Toggle | Claude 4.6 Sonnet |
| Anthropic | Toggle | Claude 4.7 Opus (Max tier required) |
| Always | Gemini 3.1 Pro | |
| NVIDIA | Always | Nemotron 3 Super 120B |
| Moonshot AI | Toggle | Kimi K2.6 |
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 |
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 tool groups:
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-5.4 |
| GPT-5.5 |
| Claude 4.6 Sonnet |
| Claude 4.7 Opus (Max tier) |
| Gemini 3.1 Pro (thinking always on) |
| Nemotron 3 Super (thinking always on) |
| Kimi K2.6 |
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, source, and auth tools (5):
Tool | Description |
| Check remaining quotas |
| List available sources/connectors and premium source quotas |
| Check authentication status |
| Send verification code to email |
| Complete auth with 6-digit code |
All query tools support source_focus: none, web, academic, social, finance, all, github, wiley, cbinsights, pitchbook, statista, raw source IDs, and comma-separated lists.
API Server
Use Perplexity models through Anthropic or OpenAI compatible API endpoints.
Start the server
pwm apiAnthropic API (Claude Code)
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=perplexity
claude --model gpt-5.4Alternatively, 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=anythingAPI Model Names
API Name | Perplexity Model | Thinking |
| Best (auto-select) | No |
| GPT-5.4 | Toggle |
| Claude 4.6 Sonnet | Toggle |
| Claude 4.7 Opus | Toggle |
| Gemini 3.1 Pro | Always |
| Nemotron 3 Super | Always |
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 last ~30 days. Re-authenticate when expired:
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")
Diagnose 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.
License
MIT
Available Tools
23 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).
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
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
Returns: Status message with authentication result and subscription tier
Inputs: code (required), email (required). Returns: Generic wrapper for non-object return types.
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: Generic wrapper for non-object return types.
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: Generic wrapper for non-object return types.
pplx_claude_opusB
Claude Opus 4.7 — Anthropic's most advanced reasoning model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_claude_opus_thinkC
Claude Opus 4.7 Thinking — Anthropic's most advanced reasoning model with extended thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_claude_sonnetD
Claude Sonnet 4.6 — Anthropic's fast model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_claude_sonnet_thinkB
Claude Sonnet 4.6 Thinking — Anthropic's fast model with extended thinking. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
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: gpt54, gpt55, claude_sonnet, claude_opus, gemini_pro, nemotron, kimi_k26
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-5.4, Claude Opus 4.7, Gemini 3.1 Pro (3 diverse providers).
Args: query: The question to ask all council models source_focus: Source aliases, raw source IDs, or comma-separated source list models: Comma-separated model names to use as council members. Available: gpt54, gpt55, claude_sonnet, claude_opus, gemini_pro, nemotron, kimi_k26. Default: "gpt54,claude_opus,gemini_pro" (3 models + synthesis = 4 Pro Searches) 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 (gpt54, gpt55, claude_sonnet, claude_opus, kimi_k26 support toggle; gemini_pro and nemotron 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: Generic wrapper for non-object return types.
pplx_deep_researchA
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: Generic wrapper for non-object return types.
pplx_gemini_pro_thinkC
Gemini 3.1 Pro Thinking — Google's most advanced model with extended thinking. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_gpt54D
GPT-5.4 — OpenAI's versatile model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_gpt54_thinkingC
GPT-5.4 Thinking — OpenAI's versatile model with extended thinking. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_gpt55C
GPT-5.5 — OpenAI's latest model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_gpt55_thinkingC
GPT-5.5 Thinking — OpenAI's latest model with extended thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_kimi_k26D
Kimi K2.6 — Moonshot's advanced model. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_kimi_k26_thinkingC
Kimi K2.6 Thinking — Moonshot's advanced model with extended thinking. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
pplx_nemotron_thinkingC
Nemotron 3 Super — NVIDIA's Nemotron 3 Super 120B model with extended thinking. COSTS 1 PRO SEARCH QUERY.
Inputs: query (required), source_focus. Returns: Generic wrapper for non-object return types.
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.
Args: query: The question to ask model: Model to use - auto, sonar, deep_research, gpt54, gpt55, claude_sonnet, claude_opus, gemini_pro, nemotron, kimi_k26 thinking: Enable extended thinking mode (available for gpt54, gpt55, claude_sonnet, claude_opus, kimi_k26; always on for gemini_pro and nemotron) source_focus: Source aliases, raw source IDs, or comma-separated source list
Inputs: query (required), model, thinking, source_focus. Returns: Generic wrapper for non-object return types.
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 aliases, raw source IDs, or comma-separated source list
Inputs: query (required), intent, source_focus. Returns: Generic wrapper for non-object return types.
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. Returns: Generic wrapper for non-object return types.
pplx_sourcesA
List live Perplexity sources/connectors available on the current account.
Args: premium_only: If True, show only premium sources with monthly limits (cbinsights, pitchbook, statista, wiley). Use this to quickly check premium quota before using expensive sources.
Inputs: premium_only. Returns: Generic wrapper for non-object return types.
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: Generic wrapper for non-object return types.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Many model-specific query tools (e.g., pplx_gpt54, pplx_sonar) and general query tools (pplx_ask, pplx_query, pplx_smart_query) have overlapping purposes. Descriptions attempt to differentiate them, but the large number of similar tools increases the chance of misselection.
The 'pplx_' prefix is consistent, but naming conventions vary: some use verb_noun (pplx_ask, pplx_query), others are model names (pplx_gpt54) or descriptive (pplx_deep_research). The mix is readable but lacks a uniform pattern.
23 tools is on the higher side for the apparent scope. While many are needed for different models and modes, the count feels slightly heavy and could be streamlined by combining model-specific tools into parameterized versions.
The tool set covers authentication, usage checking, source listing, and a variety of query types (quick, standard, deep research, council). No major gaps are apparent for interacting with Perplexity AI's capabilities.
Maintenance
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
AI tool directory MCP server, live since July 2026. Tools, agents, models, companies, services.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Web search API and MCP server for developers building AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server integrating Perplexity AI's API to offer advanced search capabilities with support for multiple models and result configuration.11,004 npm1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to perform search-augmented queries and deep multi-source research using the Perplexity API.69 npm26Apache 2.0
- AlicenseCqualityAmaintenanceEnables 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.34293 PyPI210MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to query Perplexity AI for web-grounded answers with citations and advanced search filters.369 npmMIT