Perplexity Web MCP & CLI

   
_{▶️ Watch: Latest Update Demo | Original Overview}

MCP server, CLI, and API-compatible interface for Perplexity AI's web interface.

Use your Perplexity Pro/Max subscription to access premium models (Sonar 2, GPT-6 Sol, GPT-5.6 Terra, Gemini 3.8 Flash, Claude Sonnet 5, Claude Opus 5.5, Kimi K3, GLM 5.3, Grok 4.7, and Nemotron 3 Ultra) 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
• 10 Models: Sonar 2, GPT-5.6 Terra, GPT-5.6 Sol, Gemini 3.1 Pro, Claude Sonnet 5, Claude Opus 4.8, GLM 5.2, Kimi K2.6, Grok 4.5, and Nemotron 3 Ultra
• 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

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.

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

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 gemini_pro -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-5.6 Terra, Claude Sonnet, 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 gpt56_terra,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 gpt56_terra   # 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

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

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:

Smart routing (1):

Council (1):

Usage, connectors & auth tools (5):

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-pro, nemotron, glm-5.2, claude-sonnet-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

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

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