Install the Extension

IDE	Install
Visual Studio Code
VS Code Insiders
Cursor
Windsurf
Trae
Open VSX (Gitpod · Theia · Coder)

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 15+ 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 for current version and release notes.
[^runtime]: Browser and profile details: packages/mcp-server and Architecture notes.

Who should use what?

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 – message contracts, IdeTarget / DashboardState types, and the PERPLEXITY_RULES_SECTION_START/END markers used by auto‑config.
• 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 – React 19 + Vite + Tailwind v4 + zustand dashboard. Built assets copied into packages/extension/media/webview/.
• 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 and vitest.config.ts for workspace wiring and test globs.

Quick start

Prerequisites:

• Node.js 20+
• npm (workspaces enabled)
• A Perplexity account (Free / Pro / Max)

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-<version>.vsix

Install the unpacked extension into VS Code:

code --install-extension packages/extension/perplexity-vscode-<version>.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]

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/<name>/.
• Cookies are encrypted into vault.enc (keytar with passphrase fallback).
• Any process that mutates profile state touches a .reinit sentinel, which running MCP servers watch and hot‑reload from (no restart required).

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:

{
  "tool": "perplexity_search",
  "arguments": {
    "query": "recent papers on retrieval augmented generation evaluation",
    "sources": ["scholar"],
    "language": "en-US"
  }
}

{
  "tool": "perplexity_ask",
  "arguments": {
    "query": "What are practitioners saying about Cursor versus Windsurf for large TypeScript repos?",
    "sources": ["social"],
    "mode": "copilot"
  }
}

{
  "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:

{
  "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:

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]

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.

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:

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 <configDir>/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/smoke-tests.md

Find Us

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

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.