Perplexity MCP

# Perplexity MCP for 15+ IDEs **Long‑lived Perplexity browser session, auto‑config for 20+ IDEs, and a VS Code extension – all in one monorepo.**

VS Code version npm version MCP Registry listing

VS Code installs npm downloads per week GitHub stars

CI status Latest release Last commit License


> **Not affiliated with Perplexity AI, Inc.** This is a community-maintained project. > > **Experimental** — This project is under active development and not intended for production use. APIs, tools, and behavior may change without notice.
--- ## Demo

Perplexity MCP demo — Search, Reason, Research, and Computer mode as a native MCP tool in your code editor

▶ Watch the demo on YouTube

--- ## Install the Extension
| IDE | Install | |:---:|:--------| | VS Code **Visual Studio Code** | [![Install in VS Code](https://img.shields.io/badge/Install-VS%20Code-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=Nskha.perplexity-vscode) | | VS Code Insiders **VS Code Insiders** | [![Install in VS Code Insiders](https://img.shields.io/badge/Install-VS%20Code%20Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=Nskha.perplexity-vscode) | | Cursor **Cursor** | [![Install in Cursor](https://img.shields.io/badge/Install-Cursor-000000?style=flat-square&logo=cursor&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=Nskha.perplexity-vscode) | | Windsurf **Windsurf** | [![Install in Windsurf](https://img.shields.io/badge/Install-Windsurf-0E6EFD?style=flat-square&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=Nskha.perplexity-vscode) | | Trae **Trae** | [![Install in Trae](https://img.shields.io/badge/Install-Trae-FF6B35?style=flat-square&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=Nskha.perplexity-vscode) | | Open VSX **Open VSX** (Gitpod · Theia · Coder) | [![Install on Open VSX](https://img.shields.io/badge/Install-Open%20VSX-C160EF?style=flat-square&logoColor=white)](https://open-vsx.org/extension/Nskha/perplexity-vscode) |
--- ## TL;DR – what lives here? A monorepo that ships the Perplexity MCP runtime two ways: - **`perplexity-vscode`** – native VS Code extension with an embedded MCP daemon, webview dashboard, and auto‑config for 20+ MCP‑capable IDEs.[^ver] - **`perplexity-user-mcp`** – the same MCP server as a standalone npm package for Cursor, Claude Desktop, Claude Code, Windsurf, Cline, Amp, Codex CLI, and any other MCP client that talks stdio. Both wrap a long‑lived **patchright** browser session against your existing Perplexity account, so the tools consume your logged‑in plan (Free / Pro / Max) instead of an API key.[^runtime] [^ver]: See [CHANGELOG.md](./CHANGELOG.md) for current version and release notes. [^runtime]: Browser and profile details: [packages/mcp-server](./packages/mcp-server/) and [Architecture notes](#architecture-notes). --- ## Who should use what?
You want to… Use How
Use Perplexity inside VS Code with a dashboard, login flows, and auto‑config for other IDEs. perplexity-vscode (extension) Install the VSIX or from Marketplace, run Perplexity: Login, optionally enable auto‑config.
Run the MCP server standalone for Cursor / Claude Desktop / Windsurf / Cline / Amp / Codex CLI. perplexity-user-mcp (npm CLI) npm install -g perplexity-user-mcp or npx perplexity-user-mcp, point your MCP client at it.
Keep a long‑lived HTTP MCP daemon with tunnels (Cloudflare Quick Tunnels / ngrok). Daemon mode (mcp‑server daemon/) Use the daemon entrypoint & tunnel providers under packages/mcp-server/src/daemon/.
--- ## Repo shape Four npm workspaces under packages/. Almost every aggregate task builds **shared first** because the extension host and the webview both import its contracts from source.[^shape] - **[`packages/shared`](./packages/shared/)** – message contracts, `IdeTarget` / `DashboardState` types, and the `PERPLEXITY_RULES_SECTION_START/END` markers used by auto‑config. - **[`packages/mcp-server`](./packages/mcp-server/)** – Perplexity MCP runtime. Ships standalone as `perplexity-user-mcp` and is bundled into the extension’s `dist/mcp/server.mjs` (ESM only). - **[`packages/webview`](./packages/webview/)** – React 19 + Vite + Tailwind v4 + zustand dashboard. Built assets copied into `packages/extension/media/webview/`. - **[`packages/extension`](./packages/extension/)** – VS Code extension host (CommonJS via tsup, `target: node20`). Registers the bundled MCP server via `mcpServerDefinitionProviders`, owns the webview, auto‑config, and the embedded daemon. [^shape]: See [tsconfig.base.json](./tsconfig.base.json) and [vitest.config.ts](./vitest.config.ts) for workspace wiring and test globs. --- ## Quick start Prerequisites: - Node.js **20+** - npm (workspaces enabled) - A Perplexity account (Free / Pro / Max) ```bash git clone https://github.com/Automations-Project/VSCode-Perplexity-MCP.git cd VSCode-Perplexity-MCP npm install npm run build # shared → mcp-server → webview → extension (in that order) npm test # vitest across all packages npm run package:vsix # produces packages/extension/perplexity-vscode-.vsix ``` Install the unpacked extension into VS Code: ```bash code --install-extension packages/extension/perplexity-vscode-.vsix ``` > **Build order matters.** `packages/shared` must build before the other three. The root scripts enforce this; keep that invariant when adding new scripts. --- ## Browser support matrix The MCP server automates a **real Chromium browser** via patchright to survive Cloudflare and serve Perplexity.[^browser]
Priority Runtime Env hints Notes
#1 Google Chrome PERPLEXITY_BROWSER_CHANNEL=chrome Recommended, best Cloudflare compatibility.
#2 Microsoft Edge PERPLEXITY_BROWSER_CHANNEL=msedge All three platforms, works like Chrome.
#3 System Chromium PERPLEXITY_BROWSER_CHANNEL=chromium Mainly Linux; good for headless servers.
#4 Brave auto‑detected Chromium‑based; works with no special flags.
#5 Patchright’s bundled Chromium npx patchright install chromium
then auto‑detected 		Fallback when nothing else is present.
Extra overrides: - `PERPLEXITY_BROWSER_PATH` – absolute browser executable path (wins over detection). - `PERPLEXITY_CHROME_PATH` – legacy alias for `PERPLEXITY_BROWSER_PATH`. - `PERPLEXITY_CONFIG_DIR` – overrides `~/.perplexity-mcp` (profiles, vault, daemon state). --- ## First run, profiles, and the vault Perplexity serves a Cloudflare Turnstile on first run; the server opens a headed browser for you to log in, then caches `cf_clearance` + session in `~/.perplexity-mcp/`.[^login] - Profiles live under `~/.perplexity-mcp/profiles//`. - Cookies are encrypted into `vault.enc` (keytar with passphrase fallback). On boxes without an OS keychain, run `npx perplexity-user-mcp setup-vault` to generate a strong passphrase and get OS-specific persistence snippets (PowerShell / setx / zsh / bash / systemd / MCP-client env block). - Any process that mutates profile state touches a `.reinit` sentinel, which running MCP servers watch and hot‑reload from (no restart required). v0.8.40+ also watches the active-pointer file, so switching the active profile in the extension dashboard propagates to running MCP servers automatically. - Login has a wall-clock timeout (5 min default, env-overridable) and a Cancel button in the dashboard; if the browser fallback hangs you can recover without restarting the extension. - Vault decryption transparently falls back across keychain ↔ env-var-passphrase, so a key rotation or extension-upgrade-induced unseal-preference flip won't lock you out of an existing vault. If no material can decrypt the blob, login quarantines it and writes a fresh one. Delete `~/.perplexity-mcp/` to start over completely, or use `PERPLEXITY_HEADLESS_ONLY=1` once a valid clearance is cached. --- ## Search Sources and Advanced Queries This MCP mirrors Perplexity's web app source picker more closely than the official API-key MCP server. The search-style tools accept a `sources` array with these values: - `web` - general web search. This is the default. - `scholar` - scholarly / academic source focus. - `social` - social discussion source focus. The source selector is explicit. If your MCP client calls a tool without `sources`, the server sends `["web"]`. Ask your agent for the source mode you want, or pass it directly when your client exposes tool arguments. Examples: ```json { "tool": "perplexity_search", "arguments": { "query": "recent papers on retrieval augmented generation evaluation", "sources": ["scholar"], "language": "en-US" } } ``` ```json { "tool": "perplexity_ask", "arguments": { "query": "What are practitioners saying about Cursor versus Windsurf for large TypeScript repos?", "sources": ["social"], "mode": "copilot" } } ``` ```json { "tool": "perplexity_research", "arguments": { "query": "Compare academic evidence and practitioner discussion around code review automation", "sources": ["scholar", "social"], "language": "en-US" } } ``` Natural-language prompts usually work too, as long as they are specific: - "Use Perplexity scholar sources for recent papers on agentic search evaluation." - "Search social sources for developer reports about Claude Code memory issues." - "Run deep research using both scholar and web sources, and cite every claim." - "Use `perplexity_ask` with `sources: [\"social\"]` and keep the answer concise." Useful shorthand: - "search ..." usually maps to `perplexity_search` for quick lookup and source discovery. - "ask Perplexity ..." usually maps to `perplexity_ask` for a synthesized answer with citations. - "reason through ..." usually maps to `perplexity_reason` for multi-step analysis. - "research deeply ..." usually maps to `perplexity_research` for longer reports. - "use ASI", "Computer mode", "run a compute task", or "do code/execution-style analysis" maps to `perplexity_compute` when the account has Computer-mode access. For ASI / Computer mode, ask for `perplexity_compute` by name when precision matters: ```json { "tool": "perplexity_compute", "arguments": { "query": "Model the true cost of a 5 kW residential solar installation in the Philippines versus investing the same cash at 6% annually over 10 and 20 years. Show assumptions, calculations, and sensitivity cases.", "language": "en-US" } } ``` ### Search defaults When no optional arguments are supplied: | Tool | Model default | Mode default | Sources default | Language default | |---|---|---|---|---| | `perplexity_search` | Authenticated: `pplx_pro`; anonymous: `turbo` | Authenticated: `copilot`; anonymous: `concise` | `["web"]` | `en-US` | | `perplexity_ask` | `PERPLEXITY_SEARCH_MODEL` or `pplx_pro` | `copilot` | `["web"]` | `en-US` | | `perplexity_reason` | `PERPLEXITY_REASON_MODEL` or `claude46sonnetthinking` | `copilot` | `["web"]` | `en-US` | | `perplexity_research` | `PERPLEXITY_RESEARCH_MODEL` or `pplx_alpha` | `copilot` | `["web"]` | `en-US` | | `perplexity_compute` | Tool argument, then `PERPLEXITY_COMPUTE_MODEL`, then account ASI default, then `pplx_asi` | `asi` | web-only Computer mode | `en-US` | Model defaults are configurable with environment variables: - `PERPLEXITY_SEARCH_MODEL` - `PERPLEXITY_REASON_MODEL` - `PERPLEXITY_RESEARCH_MODEL` - `PERPLEXITY_COMPUTE_MODEL` `perplexity_ask`, `perplexity_reason`, and `perplexity_compute` also accept a per-call `model` argument. `perplexity_ask` accepts `mode: "concise" | "copilot"`. `perplexity_search`, `perplexity_reason`, `perplexity_research`, and `perplexity_ask` accept `sources` and `language`. ### How requests reach Perplexity For search-style tools, the MCP server builds the same kind of request body the Perplexity web app sends: `query_str`, selected model, mode, source list, language, and optional follow-up thread context. It posts that body from the logged-in browser session to `https://www.perplexity.ai/rest/sse/perplexity_ask`. Perplexity responds as a Server-Sent Events stream. The MCP runtime reads the stream and turns it into a normal tool response: answer text, citation sources, media items, suggested follow-ups, follow-up context, and the Perplexity thread URL. This is why the server can use your existing Free / Pro / Max account features without a Perplexity API key, but it also means the request shape can drift if Perplexity changes its private web endpoint. ### Current tuning opportunities - The auto-config rules catalogue in `packages/extension/src/auto-config/index.ts` is a static copy of the tool list and summaries. Tests keep it in sync with registered tool names, but summaries and usage guidance still have to be updated by hand. A future improvement would generate the rules block from the MCP tool schemas, or share one typed catalogue between the runtime and auto-config. - `sources` defaults to `["web"]` even for queries that clearly ask for papers or social discussion. We can either document prompt patterns, as above, or add a small routing layer that infers `scholar` / `social` from the user's request before calling Perplexity. - `perplexity_search` uses browser-backed search by default. Experimental browser-free search exists behind `PERPLEXITY_EXPERIMENTAL_IMPIT_SEARCH=1`, but it is intentionally opt-in because Perplexity's private search request body can change. - `perplexity_models` already uses a warm disk cache before launching the browser. Similar cache-first behavior may help for repeated model/tier/rate-limit checks from agents. --- ## Supported IDEs / MCP clients Auto‑config writes MCP configs and rulesets for 15+ IDEs and agents; the same server also runs everywhere else.[^ide]
Client How it’s wired Config artifact
VS Code Native extension, embedded daemon, webview dashboard. settings.json, Perplexity: Login, agent MCP config.
Cursor Auto‑written MCP settings + rules section. .cursor/rules/*.mdc, mcp.json.
Claude Desktop / Claude Code Config + rules docs, upsert between markers. claude_desktop_config.json, CLAUDE.md.
Windsurf, Cline, Amp, Codex CLI MCP config and rules files per target. mcp_config.json, .rules, .github/instructions/*, etc.
Visual Studio 2022, VS Code MCP Workspace‑scoped MCP config under servers root key. <sln>/.mcp.json, .vscode/mcp.json.
OpenCode Auto‑written under mcp root key with OpenCode's local‑server entry shape. ~/.config/opencode/opencode.json, AGENTS.md.
Antigravity, Kiro, Firebase Studio, Goose, Amazon Q, LM Studio, Trae Detected and listed in the dashboard; auto‑config gated by primary‑source verification (registry only for some). .idx/mcp.json, .kiro/settings/mcp.json, ~/.gemini/antigravity/mcp_config.json, …
GitHub Copilot CLI, Factory Droid, Qwen Code User‑scoped MCP config + AGENTS.md rules section. ~/.copilot/mcp-config.json, ~/.factory/mcp.json, ~/.qwen/settings.json.
Auto‑config uses `IDE_METADATA` in `packages/shared/src/constants.ts` and upserts `PERPLEXITY-MCP-START` / `PERPLEXITY-MCP-END` sections without touching hand‑written content. --- ## Commands All commands run from the repo root. ```bash npm install npm run build # shared → mcp-server → webview → extension npm run typecheck # tsc --noEmit across all four packages npm test # builds shared, then runs vitest npm run test:coverage # vitest with v8 coverage; enforces per-file thresholds npm run package:vsix # full build + vendored deps + vsce package npm run dev:webview # Vite dev server for dashboard npm run dev:extension # tsup --watch for extension host npm run clean # rm dist + media/webview across packages ``` Single‑file / single‑test runs: ```bash npx vitest run packages/mcp-server/test/redact.test.js npx vitest run packages/extension/tests/auth-manager.login.test.ts npx vitest run -t "resolves .reinit sentinel" ``` Coverage thresholds are enforced: e.g., `redact.js` / `vault.js` ≥ 95%, `profiles.js` / `cli.js` ≥ 85%. --- ## Architecture notes A few cross‑cutting pieces that matter: - **Bundled MCP with curated externals.** `packages/extension/package.json` `build:mcp` tsups `packages/mcp-server/src/index.ts` into `dist/mcp/server.mjs`, renames `index.mjs → server.mjs`, and copies the mcp‑server `package.json` next to it. Externals (`patchright`, `got-scraping`, `tough-cookie`, `gray-matter`, `express`, `@ngrok/ngrok`, `helmet`, `keytar`, …) are deliberately left out of the bundle and vendored into `dist/node_modules/` by `packages/extension/scripts/prepare-package-deps.mjs`. - **Daemon + pluggable tunnels.** `packages/mcp-server/src/daemon/` runs a long‑lived HTTP MCP server with OAuth 2.1 (via `@modelcontextprotocol/sdk`’s `mcpAuthRouter`) and pluggable tunnels under `daemon/tunnel-providers/` (`cf-quick` and `ngrok`). Daemon state lives in `/daemon.lock`, `daemon.token`, `tunnel-settings.json`, and `ngrok.json`. - **Browser detection & download manager.** `packages/extension/src/browser/browser-detect.ts` probes Chrome → Edge → system Chromium → Brave → patchright’s Chromium, with `BrowserDownloadManager` managing `patchright install chromium` into VS Code’s globalStorage and `AuthManager` syncing env to the detached daemon. For deeper internals, see: - [`docs/release-process.md`](./docs/release-process.md) - [`docs/smoke-tests.md`](./docs/smoke-tests.md) --- ## Troubleshooting - **External MCP clients (Claude Code, Antigravity, Codex CLI, Cursor) hitting "Vault locked":** [docs/troubleshooting/external-mcp-clients.md](docs/troubleshooting/external-mcp-clients.md) --- ## Find Us
| Registry | Link | |:---------|:-----| | **VS Code Marketplace** | [`Nskha.perplexity-vscode`](https://marketplace.visualstudio.com/items?itemName=Nskha.perplexity-vscode) | | **npm** | [`perplexity-user-mcp`](https://www.npmjs.com/package/perplexity-user-mcp) | | **MCP Registry** | [`io.github.Automations-Project/perplexity-user-mcp`](https://registry.modelcontextprotocol.io) |
--- ## Support This Project This project is built and maintained with the help of AI coding tools. If you find it useful and want to support continued development (new tools, updates, bug fixes), you can contribute by gifting **Claude Code credits** — the primary tool used to build this project. Interested? [Open an issue](https://github.com/Automations-Project/VSCode-Perplexity-MCP/issues/new) or reach out to discuss feature requests and sponsorship. --- ## Contributing Contributions are welcome! Conventions: - Branch from `main` and open a PR (protected). - Run the smoke‑test checklist in `docs/smoke-tests.md` on Windows 11, macOS 14+, and Ubuntu 22+ before tagging a release. - Version `packages/extension` and `packages/mcp-server` together and add a [CHANGELOG](./CHANGELOG.md) entry that follows Keep a Changelog + SemVer. - Avoid hand‑editing auto‑managed blocks between `PERPLEXITY-MCP-START` / `PERPLEXITY-MCP-END`. --- ## License The repository is licensed under the **MIT License** – see [LICENSE](./LICENSE). > ### Important notice > > This project is an **unofficial, community‑maintained integration** for Perplexity. > It is **not affiliated with, endorsed by, or sponsored by Perplexity AI, Inc.** in any way. > > The MCP server works by automating a logged‑in Perplexity browser session on **your local machine**. > This may be considered **automated access / scraping / technical misuse** under Perplexity’s > Terms of Service and Acceptable Use Policy, and Perplexity may change or block this behaviour > at any time. > > By using this project, **you are solely responsible for ensuring your use complies with > Perplexity’s terms, policies, and any applicable law**, and you accept the risk that your > Perplexity account could be rate‑limited, suspended, or terminated. > > This software is provided **“as is”**, on an **experimental** basis, **without any warranty**. > Do not use it for anything where reliability, correctness, or policy compliance are critical.