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.¹
• 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.²

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

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

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.

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.