Skip to content
Back to search

perplexity-web-mcp

MCP server and Anthropic API-compatible interface for Perplexity AI web interface

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jacob-bd/perplexity-web-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jacob-bd/perplexity-web-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jacob-bd--perplexity-web-mcp/badge.svg)](/listings/jacob-bd--perplexity-web-mcp)

HTML

<a href="/listings/jacob-bd--perplexity-web-mcp"><img src="/api/listings/jacob-bd--perplexity-web-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 709 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/logo.png" alt="Perplexity Web MCP" width="700">
  3. </p>
  4. # Perplexity Web MCP & CLI
  5. [![PyPI version](https://img.shields.io/pypi/v/perplexity-web-mcp-cli)](https://pypi.org/project/perplexity-web-mcp-cli/)
  6. [![PyPI downloads](https://img.shields.io/pypi/dm/perplexity-web-mcp-cli)](https://pypistats.org/packages/perplexity-web-mcp-cli)
  7. [![Total downloads](https://static.pepy.tech/badge/perplexity-web-mcp-cli)](https://pepy.tech/projects/perplexity-web-mcp-cli)
  8. [![Python](https://img.shields.io/pypi/pyversions/perplexity-web-mcp-cli)](https://pypi.org/project/perplexity-web-mcp-cli/)
  9. [![License](https://img.shields.io/pypi/l/perplexity-web-mcp-cli)](https://github.com/jacob-bd/perplexity-web-mcp/blob/main/LICENSE)
  10. <p align="center">
  11. <a href="https://youtu.be/9xyClDvmoZ0">
  12. <img src="https://img.youtube.com/vi/9xyClDvmoZ0/maxresdefault.jpg" alt="Perplexity Powerhouse + Model Council Demo" width="400">
  13. </a>
  14. &nbsp;&nbsp;&nbsp;
  15. <a href="https://youtu.be/ffyibtyk-LQ">
  16. <img src="https://img.youtube.com/vi/ffyibtyk-LQ/maxresdefault.jpg" alt="Demo Overview" width="400">
  17. </a>
  18. <br>
  19. <sub>▶️ <strong>Watch: <a href="https://youtu.be/9xyClDvmoZ0">Latest Update Demo</a> | <a href="https://youtu.be/ffyibtyk-LQ">Original Overview</a></strong></sub>
  20. </p>
  21. MCP server, CLI, and API-compatible interface for Perplexity AI's web interface.
  22. 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.
  23. ## Features
  24. - **CLI**: Query Perplexity models directly from the terminal (`pwm ask`, `pwm chat`, `pwm council`, `pwm research`, `pwm config`)
  25. - **MCP Server**: MCP tools for AI agents with citations, rate limit checking, and multi-turn context
  26. - **API Server**: Drop-in Anthropic Messages API and OpenAI Chat Completions API
  27. - **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
  28. - **Thinking Mode**: Extended thinking support for all compatible models
  29. - **Deep Research**: Full support for Perplexity's Deep Research mode
  30. - **Multi-Turn Conversations**: State-preserved threaded conversations for both MCP and CLI REPL
  31. - **Model Council**: Query multiple models in parallel and get a synthesized consensus
  32. - **Setup & Skill Management**: Auto-configure MCP for Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Cline, Antigravity; install Agent Skills across 9 platforms
  33. - **Doctor**: Diagnose installation, auth, config, rate limits, and skill status
  34. ## Vibe Coding Alert
  35. 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.
  36. 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.
  37. > [!WARNING]
  38. > **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**.
  39. **If you know better, teach us.** PRs, issues, and architectural advice are all welcome. This is open source specifically because human expertise is irreplaceable.
  40. ---
  41. ## Installation
  42. ### From PyPI (recommended)
  43. **Using uv:**
  44. ```bash
  45. uv tool install perplexity-web-mcp-cli
  46. ```
  47. **Using pipx:**
  48. ```bash
  49. pipx install perplexity-web-mcp-cli
  50. ```
  51. **Using pip:**
  52. ```bash
  53. pip install perplexity-web-mcp-cli
  54. ```
  55. > **Note:** Requires Python 3.10-3.13.
  56. ### From source (for development)
  57. ```bash
  58. git clone https://github.com/jacob-bd/perplexity-web-mcp.git
  59. cd perplexity-web-mcp
  60. uv venv && source .venv/bin/activate
  61. uv pip install -e .
  62. ```
  63. ### Upgrading
  64. ```bash
  65. pip install --upgrade perplexity-web-mcp-cli
  66. ```
  67. After upgrading, restart your MCP client (Claude Code, Cursor, etc.) to reload the server.
  68. ---
  69. ## Quick Start
  70. ```bash
  71. # 1. Authenticate
  72. pwm login
  73. # 2. Ask a question
  74. pwm ask "What is quantum computing?"
  75. # 3. Chat interactively (keeps one thread across turns)
  76. pwm chat
  77. # 4. Deep research
  78. pwm research "agentic AI trends 2026"
  79. # 5. Check your remaining quotas
  80. pwm usage
  81. # 6. Set up MCP for your AI tools
  82. pwm setup add all # Interactive setup for all detected tools
  83. pwm setup add cursor # Or add individually
  84. # 7. Install the Agent Skill
  85. pwm skill install claude-code
  86. # 8. Diagnose any issues
  87. pwm doctor
  88. ```
  89. ---
  90. ## CLI Reference
  91. ### Querying
  92. Ask Perplexity a question. By default, Perplexity auto-selects the best model.
  93. ```bash
  94. pwm ask "What is quantum computing?"
  95. ```
  96. **Choose a specific model** with `-m` (see [Models](#models) for the full list):
  97. ```bash
  98. pwm ask "Compare React and Vue" -m gpt61_sol
  99. ```
  100. ```bash
  101. pwm ask "Explain the attention mechanism" -m claude_sonnet
  102. ```
  103. **Enable extended thinking** with `-t` for deeper reasoning (available on models with Toggle thinking):
  104. ```bash
  105. pwm ask "Prove that the square root of 2 is irrational" -m claude_sonnet --thinking
  106. ```
  107. **Focus on specific sources** with `-s` to control where Perplexity searches:
  108. ```bash
  109. # Search only academic papers and scholarly articles
  110. pwm ask "transformer architecture improvements 2025" -s academic
  111. # Search only social media (Reddit, Twitter, etc.)
  112. pwm ask "best mechanical keyboard 2026" -s social
  113. # Search SEC EDGAR financial filings
  114. pwm ask "Apple revenue Q4 2025" -s finance
  115. # Search all source types at once
  116. pwm ask "latest AI news" -s all
  117. # Search an account connector source, when your Perplexity account exposes one
  118. pwm connectors list
  119. pwm ask "recent funding for Stripe" -s pitchbook_mcp_cashmere
  120. ```
  121. **Output options:**
  122. ```bash
  123. # JSON output (for piping to other tools)
  124. pwm ask "What is Rust?" --json
  125. # Suppress citation URLs (answer text only)
  126. pwm ask "What is Rust?" --no-citations
  127. ```
  128. **Combine flags** for full control:
  129. ```bash
  130. pwm ask "recent advances in protein folding" -m gemini4_hydrogen -s academic --json
  131. ```
  132. **Long prompts and attachments:**
  133. ```bash
  134. # Read the prompt from stdin
  135. cat question.txt | pwm ask -
  136. # Or from a UTF-8 file
  137. pwm ask --prompt-file question.txt
  138. # Attach PDFs or images (repeatable)
  139. pwm ask "Summarize the key risks" --file report.pdf
  140. ```
  141. ### Interactive Chat
  142. `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`.
  143. ```bash
  144. pwm chat # defaults to Sonar, web sources
  145. pwm chat -m auto # quota-aware model routing
  146. pwm chat -m claude_sonnet --thinking # start with a specific model
  147. ```
  148. 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.
  149. ### Saved Defaults
  150. 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.
  151. ```bash
  152. pwm config set --model grok47 --thinking --source web
  153. pwm config show
  154. pwm config clear # or clear one key: pwm config clear model
  155. ```
  156. ### Deep Research
  157. Run Perplexity's Deep Research mode for in-depth reports with extensive sources. Uses a separate **monthly** quota.
  158. ```bash
  159. pwm research "agentic AI trends 2026"
  160. ```
  161. ```bash
  162. pwm research "climate policy impact on renewable energy" -s academic
  163. ```
  164. ```bash
  165. pwm research "NVIDIA competitive landscape" -s finance --json
  166. ```
  167. ### Model Council
  168. 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).
  169. ```bash
  170. # Default: GPT-6.1 Sol, Claude Sonnet 5.5, Gemini 4 Hydrogen + Sonar 2 synthesis (4 Pro Searches)
  171. pwm council "What are best practices for microservices?"
  172. ```
  173. ```bash
  174. # Custom model selection
  175. pwm council "Compare Rust and Go" -m gpt61_sol,claude_sonnet
  176. ```
  177. ```bash
  178. # Enable extended thinking for all council models
  179. pwm council "Prove the Pythagorean theorem" --thinking
  180. ```
  181. ```bash
  182. # Skip synthesis, output as JSON
  183. pwm council "React vs Vue" --no-synthesis --json
  184. ```
  185. ### Authentication
  186. ```bash
  187. pwm login # Interactive login (email + OTP)
  188. pwm login --check # Check if authenticated
  189. pwm login --email user@example.com # Send verification code (non-interactive)
  190. pwm login --email user@example.com --code 123456 # Complete auth with code
  191. pwm login --email user@example.com --code 123456 --totp-code 654321 # Account with TOTP enabled
  192. ```
  193. Set `PWM_SAVE_TO_LIBRARY=1` to save shared CLI and MCP queries to the Perplexity thread library. Queries are
  194. incognito by default.
  195. ### Usage & Limits
  196. ```bash
  197. pwm usage # Check remaining rate limits
  198. pwm usage --refresh # Force-refresh from Perplexity servers
  199. ```
  200. ### Models
  201. ```bash
  202. pwm models # List the live model catalog (free, no query quota)
  203. pwm models --refresh # Force a fresh fetch from Perplexity
  204. pwm models --json # Machine-readable output
  205. ```
  206. 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=...)`.
  207. ### Hack
  208. 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.
  209. ```bash
  210. pwm hack claude # Launch Claude Code
  211. pwm hack claude -m gpt61_sol # Launch Claude Code with a specific model
  212. ```
  213. ### MCP Setup
  214. ```bash
  215. pwm setup list # Show supported tools and MCP configuration status
  216. pwm setup add all # Interactive: detect and configure all tools
  217. pwm setup add claude-code # Add MCP server to Claude Code
  218. pwm setup add cursor # Add MCP server to Cursor
  219. pwm setup add codex # Add MCP server to Codex CLI
  220. pwm setup add gemini # Add MCP server to Gemini CLI
  221. pwm setup add windsurf # Add MCP server to Windsurf
  222. pwm setup add cline # Add MCP server to Cline CLI
  223. pwm setup add antigravity # Add MCP server to Antigravity
  224. pwm setup remove all # Remove from all configured tools
  225. pwm setup remove cursor # Remove MCP server from a tool
  226. ```
  227. For clients that support HTTP/SSE, or when multiple sessions should share one
  228. MCP process, run the local daemon:
  229. ```bash
  230. pwm serve-mcp --transport streamable-http # Start HTTP MCP on 127.0.0.1:8000/mcp
  231. pwm serve-mcp --status # Check daemon status
  232. pwm serve-mcp --stop # Stop the daemon
  233. pwm setup add codex --http # Configure Codex for Streamable HTTP
  234. pwm serve-mcp --transport sse # Start the legacy SSE transport
  235. ```
  236. The HTTP transports bind to loopback by default. Keep the daemon on a loopback
  237. address unless you put an authenticated reverse proxy in front of it.
  238. ### Skill Management
  239. ```bash
  240. pwm skill list # Show installation status per platform
  241. pwm skill install claude-code # Install skill for Claude Code
  242. pwm skill install cursor --level project # Install at project level
  243. pwm skill uninstall gemini-cli # Remove skill
  244. pwm skill update # Update all outdated skills
  245. pwm skill show # Display skill content
  246. ```
  247. ### Doctor
  248. ```bash
  249. pwm doctor # Diagnose installation, auth, config, limits
  250. pwm doctor -v # Verbose (includes security + per-platform skill status)
  251. ```
  252. ### AI Documentation
  253. ```bash
  254. pwm --ai # Print comprehensive AI-optimized reference
  255. ```
  256. ---
  257. ## Models
  258. | CLI Name | Provider | Thinking | Notes |
  259. | ------------------ | ---------- | -------- | ------------------------------------------------ |
  260. | `auto` | Perplexity | No | Auto-selects best model |
  261. | `sonar` | Perplexity | No | Sonar 2 (latest in-house; API id `experimental`) |
  262. | `deep_research` | Perplexity | No | Monthly quota, in-depth reports |
  263. | `gpt61_sol` | OpenAI | Toggle | GPT-6.1 Sol |
  264. | `gpt6_astra` | OpenAI | Toggle | GPT-6 Astra (Max tier required) |
  265. | `gemini4_carbon` | Google | Toggle | Gemini 4 Carbon (Max tier required) |
  266. | `gemini4_hydrogen` | Google | Toggle | Gemini 4 Hydrogen |
  267. | `claude_sonnet` | Anthropic | Toggle | Claude Sonnet 5.5 |
  268. | `claude_opus` | Anthropic | Toggle | Claude Opus 5.5 (Max tier required) |
  269. | `claude_opus55` | Anthropic | Toggle | Alias for Claude Opus 5.5 (Max tier required) |
  270. | `claude_fable52` | Anthropic | Toggle | Claude Fable 5.2 (Max tier required) |
  271. | `grok47` | xAI | Toggle | Grok 4.7 |
  272. | `nemotron` | NVIDIA | No | Nemotron 3.5 Super VL (text-only) |
  273. | `glm53` | Z.ai | Always | GLM 5.3 |
  274. | `kimi_k3` | Moonshot | Always | Kimi K3 |
  275. The catalog is server-driven: run `pwm models` to see the live model list (free, no query quota),
  276. and any identifier it shows can be passed to `pwm ask -m <identifier>`.
  277. ### Source Focus
  278. Control where Perplexity searches using `-s` (CLI) or `source_focus` (MCP):
  279. | Option | Description | Example Use Case |
  280. | ---------- | -------------------------------- | ---------------------------------------------- |
  281. | `web` | General web search (default) | News, general questions |
  282. | `academic` | Academic papers, journals | Research, citations, scientific topics |
  283. | `social` | Reddit, Twitter, forums | Opinions, recommendations, community sentiment |
  284. | `finance` | SEC EDGAR filings | Company financials, regulatory filings |
  285. | `all` | Web + Academic + Social combined | Broad coverage across all sources |
  286. ### Account Connector Sources
  287. Accounts with Perplexity connectors may expose additional source IDs such as `pitchbook_mcp_cashmere` or `cbinsights_mcp_cashmere`. List IDs before using them:
  288. ```bash
  289. pwm connectors list
  290. pwm ask "recent funding for Stripe" -s pitchbook_mcp_cashmere
  291. ```
  292. MCP clients should call `pplx_connectors()` first, then pass the returned ID as `source_focus`.
  293. 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](docs/connectors.md) for the full trust-boundary guidance.
  294. ---
  295. ## MCP Server
  296. ### Setup
  297. The easiest way to configure MCP:
  298. ```bash
  299. pwm setup add claude-code
  300. ```
  301. Or configure manually for any MCP client:
  302. **Claude Code CLI:**
  303. ```bash
  304. claude mcp add perplexity pwm-mcp
  305. ```
  306. **Claude Desktop** — Download the `.mcpb` extension from the [latest release](https://github.com/jacob-bd/perplexity-web-mcp/releases/latest) and open it with Claude Desktop. Or configure manually:
  307. ```json
  308. {
  309. "mcpServers": {
  310. "perplexity": {
  311. "command": "pwm-mcp"
  312. }
  313. }
  314. }
  315. ```
  316. **Cursor** (`~/.cursor/mcp.json`):
  317. ```json
  318. {
  319. "mcpServers": {
  320. "perplexity": {
  321. "command": "pwm-mcp"
  322. }
  323. }
  324. }
  325. ```
  326. ### Available MCP Tools
  327. **Query tools:**
  328. | Tool | Description |
  329. | ------------------------------------------------------ | ------------------------------------------- |
  330. | `pplx_query` | Flexible: model selection + thinking toggle |
  331. | `pplx_ask` | Quick Q&A (auto-selects best model) |
  332. | `pplx_deep_research` | In-depth reports with sources |
  333. | `pplx_sonar` | Perplexity Sonar 2 (1 Pro Search) |
  334. | `pplx_gpt61_sol` / `pplx_gpt61_sol_thinking` | GPT-6.1 Sol |
  335. | `pplx_gpt6_astra` / `pplx_gpt6_astra_thinking` | GPT-6 Astra (Max tier) |
  336. | `pplx_gemini4_carbon` / `pplx_gemini4_carbon_thinking` | Gemini 4 Carbon (Max tier) |
  337. | `pplx_gemini4_hydrogen` / `..._thinking` | Gemini 4 Hydrogen |
  338. | `pplx_claude_sonnet` / `pplx_claude_sonnet_think` | Claude Sonnet 5.5 |
  339. | `pplx_claude_opus` / `pplx_claude_opus_think` | Claude Opus 5.5 (Max tier) |
  340. | `pplx_claude_fable52` / `pplx_claude_fable52_think` | Claude Fable 5.2 (Max tier) |
  341. | `pplx_grok47` / `pplx_grok47_thinking` | Grok 4.7 |
  342. | `pplx_nemotron` | Nemotron 3.5 Super VL |
  343. | `pplx_glm53` | GLM 5.3 (thinking always on) |
  344. | `pplx_kimi_k3` | Kimi K3 (thinking always on) |
  345. **Smart routing (1):**
  346. | Tool | Description |
  347. | ------------------ | ------------------------------------------------------------- |
  348. | `pplx_smart_query` | Quota-aware routing — auto-selects best model based on limits |
  349. **Council (1):**
  350. | Tool | Description |
  351. | -------------- | --------------------------------------------------------- |
  352. | `pplx_council` | Query multiple models in parallel with optional synthesis |
  353. **Usage, connectors & auth tools (5):**
  354. | Tool | Description |
  355. | ------------------------ | -------------------------------------- |
  356. | `pplx_usage` | Check remaining quotas |
  357. | `pplx_connectors` | List connector source IDs |
  358. | `pplx_auth_status` | Check authentication status |
  359. | `pplx_auth_request_code` | Send verification code to email |
  360. | `pplx_auth_complete` | Complete email and TOTP authentication |
  361. All query tools support `source_focus`: `none`, `web`, `academic`, `social`, `finance`, `all`, or a connector source ID returned by `pplx_connectors()`.
  362. ---
  363. ## API Server
  364. Use Perplexity models through Anthropic or OpenAI compatible API endpoints.
  365. ### Start the server
  366. ```bash
  367. pwm api
  368. ```
  369. The server binds to `127.0.0.1` by default. A non-loopback `--host` or `HOST`
  370. value is rejected unless `PWM_API_KEY` (or the legacy `ANTHROPIC_API_KEY`)
  371. contains a non-empty secret. Remote use should also be protected by a trusted
  372. TLS reverse proxy and firewall rules because the built-in server serves plain
  373. HTTP. Clients may send the configured secret as `x-api-key` or
  374. `Authorization: Bearer <secret>`.
  375. When an API key is configured, the same authentication applies to every API
  376. endpoint, including the `/v1/responses` WebSocket route. The server rejects
  377. unauthenticated WebSocket connections before accepting the connection.
  378. ### Anthropic API (Claude Code)
  379. ```bash
  380. export ANTHROPIC_BASE_URL=http://localhost:8080
  381. export ANTHROPIC_API_KEY=perplexity
  382. claude --model gpt-5.6-terra
  383. ```
  384. Alternatively, launch Claude Code seamlessly using the `hack` command, which automatically starts the API server and configures the environment for you:
  385. ```bash
  386. pwm hack claude
  387. ```
  388. ### OpenAI API
  389. ```bash
  390. export OPENAI_BASE_URL=http://localhost:8080/v1
  391. export OPENAI_API_KEY=anything
  392. ```
  393. ### Codex CLI Integration
  394. 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`).
  395. 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:
  396. ```bash
  397. export OPENAI_API_BASE=http://localhost:8080/v1
  398. export OPENAI_API_KEY=dummy
  399. codex -m sonar --local-provider lmstudio
  400. ```
  401. 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"`.
  402. ### API Model Names
  403. | API Name | Perplexity Model | Thinking |
  404. | ----------------------- | --------------------- | -------- |
  405. | `perplexity-auto` | Best (auto-select) | No |
  406. | `gpt-6.1-sol` | GPT-6.1 Sol | Toggle |
  407. | `gpt-6-astra` | GPT-6 Astra | Toggle |
  408. | `gemini-4-carbon` | Gemini 4 Carbon | Toggle |
  409. | `gemini-4-hydrogen` | Gemini 4 Hydrogen | Toggle |
  410. | `claude-sonnet-5-5` | Claude Sonnet 5.5 | Toggle |
  411. | `claude-opus-5-5` | Claude Opus 5.5 | Toggle |
  412. | `claude-fable-5-2` | Claude Fable 5.2 | Toggle |
  413. | `grok-4.7` | Grok 4.7 | Toggle |
  414. | `glm-5.3` / `glm53` | GLM 5.3 | Always |
  415. | `nemotron-3.5-super-vl` | Nemotron 3.5 Super VL | No |
  416. Legacy aliases (`claude-3-5-sonnet`, `claude-3-opus`) are supported for compatibility.
  417. ---
  418. ## Python API
  419. ```python
  420. from perplexity_web_mcp import Perplexity, ConversationConfig, Models
  421. client = Perplexity(session_token="your_token")
  422. conversation = client.create_conversation(
  423. ConversationConfig(model=Models.CLAUDE_45_SONNET)
  424. )
  425. conversation.ask("What is quantum computing?")
  426. print(conversation.answer)
  427. for result in conversation.search_results:
  428. print(f"Source: {result.url}")
  429. # Follow-up (context preserved)
  430. conversation.ask("Explain it simpler")
  431. print(conversation.answer)
  432. ```
  433. ---
  434. ## Subscription Tiers & Rate Limits
  435. | Tier | Cost | Pro Search | Deep Research | Labs |
  436. | ---- | ------- | ----------- | ------------- | ------------ |
  437. | Free | $0 | 3/day | 1/month | No |
  438. | Pro | $20/mo | Weekly pool | Monthly pool | Monthly pool |
  439. | Max | $200/mo | Weekly pool | Monthly pool | Monthly pool |
  440. The MCP server checks quotas before each query. Use `pwm usage` or `pplx_usage` to check your limits.
  441. ---
  442. ## Troubleshooting
  443. ### Authentication Errors (403)
  444. 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:
  445. ```bash
  446. pwm login
  447. ```
  448. **Non-interactive (for AI agents):**
  449. ```bash
  450. pwm login --email your@email.com
  451. ```
  452. ```bash
  453. pwm login --email your@email.com --code 123456
  454. ```
  455. **Via MCP tools (for AI agents without shell):**
  456. 1. Call `pplx_auth_request_code(email="your@email.com")`
  457. 2. Check email for 6-digit code
  458. 3. Call `pplx_auth_complete(email="your@email.com", code="123456")`
  459. If the tool returns `TOTP_REQUIRED`, call it again with
  460. `pplx_auth_complete(email="your@email.com", totp_code="654321")`.
  461. ### Session Expired or Zeroed Limits
  462. 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:
  463. ```bash
  464. pwm login
  465. ```
  466. `pwm doctor` also verifies the stored session and reports `token invalid or expired` when a fresh login is needed.
  467. ### Blank or Truncated Answers
  468. 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:
  469. ```bash
  470. uv tool upgrade perplexity-web-mcp-cli
  471. pwm --version
  472. ```
  473. ### Diagnose Issues
  474. ```bash
  475. pwm doctor
  476. ```
  477. This checks installation, authentication, rate limits, MCP configuration, and skill installation -- with fix suggestions for every issue found.
  478. ### Rate Limiting
  479. - **CLI/MCP**: Auto-checks quotas before each query, blocks if exhausted
  480. - **API server**: Enforces 5-second minimum between requests
  481. ---
  482. ## Agent Skill
  483. This project includes a portable [Agent Skill](https://agentskills.io/) (SKILL.md) that teaches AI agents how to use the CLI and MCP tools. Install it for your platform:
  484. ```bash
  485. pwm skill install all # Install for all detected tools
  486. pwm skill install claude-code # Or install individually
  487. pwm skill install cursor
  488. pwm skill install codex
  489. pwm skill install gemini-cli
  490. pwm skill install antigravity
  491. pwm skill install cline
  492. pwm skill install opencode
  493. pwm skill install openclaw
  494. pwm skill install alef-agent
  495. ```
  496. The skill follows Anthropic's Agent Skills open standard and works across any compliant AI platform.
  497. ---
  498. ## Credits
  499. Originally forked from [perplexity-webui-scraper](https://github.com/henrique-coder/perplexity-webui-scraper) by [henrique-coder](https://github.com/henrique-coder).
  500. ## Support
  501. 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. 🙏
  502. <a href="https://buymeacoffee.com/jacobbd"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="42"></a>
  503. ## License
  504. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.