perplexity-web-mcp
Connects to a user's Perplexity web session via Playwright to run AI web searches and research: lists and selects models, performs searches and advanced searches (with source extraction and inline citation provenance), fans out one prompt across 2-5 models for comparison/consensus, verifies claims against cited sources, follows up on long threads via thread URLs, and offers health checks and login. Optionally uses Perplexity's official Agent API backend instead of the browser for lower-latency searches.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@perplexity-web-mcp search the web for the latest React 19 release notes and cite sources"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Perplexity Web Orchestrator (perplexity-web-mcp)
Portable MCP stdio server + perplexity-orchestrator skill bundle for connecting AI coding agents (Claude Code, Cursor, OpenCode, Antigravity, and other MCP clients) to your Perplexity web session via Playwright.
Privacy & Sharing Notice: This bundle is sanitized — it contains no
.playwright/session cookies, noconfig.json, no cached/diagnostic/output dumps, and no user-specific file paths..gitignoreexcludesnode_modules/,.playwright/,cache/,diagnostics/,outputs/,eval-results/, andconfig.jsonso it can be shared safely as a Git repo or zip archive.
Included Features
7 MCP Tools:
list_models,set_default_model,search,search_advanced,compare_models,health_check, andlogin.Claim-to-Source Verification (
verify_claims): Passverify_claims: true(or setPERPLEXITY_VERIFY_CLAIMS=1) to fetch cited pages, match dates/versions/numbers/names, and tag each claimsupported,weak, orunverified.Multi-Model Comparison (
compare_models): Fan out one prompt across2–5models concurrently usingPERPLEXITY_PROFILE_DIRSbrowser pool slots (or parallel official API calls) and summarize agreed facts, divergent specifics, and shared citations.UI Health Check & Failure Snapshots (
health_check): Verify login, Cloudflare clear state, search input,+/sources trigger, hydrated model selector, and local dirs in seconds, auto-saving.html/.png/.jsondebug snapshots under./diagnostics/when Perplexity selectors break.Query Result Cache (
no_cache): Replays repeated non-thread queries within3600s(PERPLEXITY_CACHE_TTL_SECONDS,0disables) instantly from./cache/.Virtualized Long-Thread Follow-Ups: Correctly detects new follow-up turns even when Perplexity virtualizes old DOM
.prosenodes (turnCount&virtualizedThreadreported inMetadata).15-Minute Default Timeout (
900s): Long reasoning prompts and Pro models get900sby default, configurable per request viatimeout_seconds(up to1800s/ 30 min) or globally via--timeout=<seconds>.Non-Intrusive Minimized Browser: Launches headed Chromium off-screen and minimizes it so interactive browsing stays out of your way while avoiding headless bot blocks.
Clean Lifecycle Management: Cleans up stale Chromium profile locks on startup and shuts down cleanly on
stdinclose,SIGINT,SIGTERM, andSIGHUP.Cancellation-Safe & Progress-Aware (
@modelcontextprotocol/sdk): Listens to MCPnotifications/cancelled(AbortSignal), aborts queued/in-flight waits cleanly, emitsnotifications/progressupdates every~5s, and persists incremental-partial.txtcheckpoints every~30s(or immediately on abort/timeout).Claim-Level Citation Provenance: Preserves inline
[1],[2]citation references inside answers (data-pplx-citation-urlpills + anchor tags), maps claims to cited URLs (Claim Provenancesection in.txt/ compact answers), and hovers top citation cards (<=1.8sbudget) to recover page titles, snippets, dates, and multi-source links.Optional Official Agent API Hybrid (
PERPLEXITY_API_KEY): Passbackend: "api"(or setPERPLEXITY_API_KEYwithbackend: "auto") to call Perplexity's official/v1/agentendpoint directly (1–5slatency, officialsearch_resultssnippets/dates, zero UI scraping/ToS exposure) while keeping Playwright Pro browser mode as the zero-extra-cost default.Structured Typed Errors & Metadata JSON: Returns typed JSON error payloads (
LOGIN_REQUIRED,CLOUDFLARE_CHALLENGE,SELECTOR_MISSING,MODEL_UNAVAILABLE,CANCELLED,TIMEOUT,INVALID_PARAMS,PROFILE_UNAVAILABLE,API_ERROR), extracts up to50sources by default (PERPLEXITY_MAX_SOURCES) plus downloadable attachment links, and appends a compactMetadataJSON line.Poolable Concurrent Browser Profiles: Supports
PERPLEXITY_PROFILE_DIRS(semicolon/comma-separated profile directories) and per-callprofilearguments (list_models,search,search_advanced,compare_models,health_check,login) with independent per-profile browser contexts and queues so multiple agents/calls can run in parallel.Long-Output
.txtFile Spooling: Answers at or above15000chars (or any query passed withoutput_file) automatically save to a UTF-8.txtfile (./outputs/by default) and return a compact preview, counts, sources, andThread URLso coding agents can read large results in slices instead of overflowing context.Portable Profile Path: Defaults to
./.playwright/profileinside this directory, or acceptsPERPLEXITY_PROFILE_DIRto point each agent or workspace to a specific profile folder.Cross-Agent Skill + Test/Eval Suite (
npm test,npm run eval): Includesskills/perplexity-orchestrator/SKILL.mdimplementing the Discover -> Research -> Iterate (thread_url) -> Compare -> Test -> Adopt workflow,node --testunit/DOM/protocol tests, and an 18-question live evaluation runner.
Related MCP server: playwright-browser
Folder Structure
perplexity-web-orchestrator/
├── dist/
│ ├── index.js # MCP SDK stdio entry point (7 tools, progress, cancellation, typed errors)
│ ├── browser.js # Poolable Playwright profile manager, off-screen/minimized handling, cleanup
│ ├── auth.js # Cancellation-safe session check & interactive login flow
│ ├── search.js # Model/source selection, virtualized-thread detection, health_check, provenance
│ ├── compare.js # compare_models multi-model fan-out & consensus analysis
│ ├── facts.js # Key-fact extractor (dates, versions, numbers+units, names)
│ ├── verify.js # Claim-to-source HTTP verification (supported / weak / unverified)
│ ├── cache.js # File-backed TTL query cache
│ ├── diagnostics.js # Failure .html/.png/.json snapshot saver
│ ├── api.js # Optional Perplexity official /v1/agent REST backend
│ ├── output.js # Long-output .txt spooling, Claim Provenance, checkpoints, metadata
│ └── errors.js # Typed PerplexityMcpError codes and normalization
├── eval/
│ ├── questions.json # 18 fixed benchmark prompts (coding, documentation, current events)
│ └── run-eval.js # Benchmark runner (`npm run eval`)
├── test/
│ └── *.test.js # Unit, DOM, and stdio MCP integration suite (`npm test`)
├── configs/
│ ├── claude-code.mcp.json
│ ├── cursor.mcp.json
│ ├── opencode.json
│ └── antigravity.mcp_config.json
├── skills/
│ └── perplexity-orchestrator/
│ └── SKILL.md
├── CHANGELOG.md
├── .gitignore
├── LICENSE # MIT (upstream quequiere/perplexity-web-mcp)
├── package.json
└── README.mdQuick Setup
1. Prerequisites (For New Machines / Shared Recipients)
Requires Node.js >= 20. Inside the copied directory:
npm install --omit=dev
npx playwright install chromium(If you are using G:/perplexity-web-orchestrator directly on the machine where it was prepared, node_modules and Chromium are already installed.)
2. First-Time Perplexity Login
The first time any agent calls a perplexity-web tool, or when you explicitly run login, a Chromium window opens on https://www.perplexity.ai/ so you can sign in once. Session cookies are stored locally in .playwright/profile (git-ignored) unless overridden by PERPLEXITY_PROFILE_DIR.
3. Connect Your Coding Agent
Replace G:/perplexity-web-orchestrator below if you cloned or moved this folder somewhere else.
Claude Code
MCP config: Copy
configs/claude-code.mcp.jsoninto your project's.mcp.jsonor merge theperplexity-webentry into~/.claude.json, or run:claude mcp add perplexity-web -- node G:/perplexity-web-orchestrator/dist/index.jsSkill: Copy
skills/perplexity-orchestrator/into:Global:
~/.claude/skills/perplexity-orchestrator/SKILL.mdProject:
.claude/skills/perplexity-orchestrator/SKILL.md
Cursor
MCP config: Merge
configs/cursor.mcp.jsoninto~/.cursor/mcp.json(global) or.cursor/mcp.json(project).Skill: Copy
skills/perplexity-orchestrator/into.cursor/skills/perplexity-orchestrator/SKILL.md(or~/.cursor/skills/perplexity-orchestrator/SKILL.md).
OpenCode
MCP config: Merge
configs/opencode.jsoninto~/.config/opencode/opencode.json(global) or./opencode.json(project).Skill: Copy
skills/perplexity-orchestrator/into:Global:
~/.config/opencode/skills/perplexity-orchestrator/SKILL.mdProject:
.opencode/skills/perplexity-orchestrator/SKILL.md
Antigravity
MCP config: Merge
configs/antigravity.mcp_config.jsoninto~/.gemini/config/mcp_config.json.Skill: Copy
skills/perplexity-orchestrator/into~/.gemini/config/skills/perplexity-orchestrator/SKILL.md.
Environment Variables & CLI Options
Option | Default | Description |
|
| CLI flag overriding the default search timeout in |
|
| Override directory used to store default Chromium profile & Perplexity cookies. |
| (unset) | Semicolon/comma-separated list of profile directories for automatic concurrent multi-browser pooling. |
|
| Base folder for named |
|
| Maximum cited links extracted per answer ( |
|
| Directory where long responses ( |
|
| Character threshold for automatic |
|
| Set |
| (unset) | Optional official Perplexity API key; enables fast |
|
| Default model ID when using |
|
| Effort level ( |
|
| Default backend policy ( |
|
| Set |
|
| TTL in seconds for repeated non-thread queries ( |
|
| Directory storing cached JSON search responses. |
|
| Directory storing failure |
Testing & Evaluation
npm run check # Syntax-check all 12 runtime modules + eval script
npm test # Run offline unit, headless DOM, and stdio MCP protocol tests
npm run eval # Run the 18-question live evaluation benchmark (flags: --limit=N, --category=coding|documentation|current, --model=..., --backend=..., --verify, --timeout=120, --dry-check)Running Multiple Agents Safely
Chromium locks a profile directory so only one active browser process can use a given PERPLEXITY_PROFILE_DIR at a time.
Option A (Simplest): Point all agents at
G:/perplexity-web-orchestrator, log in once, and run Perplexity queries from one active agent session at a time.Option B (Parallel agents): Give a second agent its own
PERPLEXITY_PROFILE_DIRin its MCPenvblock (e.g.,G:/perplexity-profiles/claude-code) and runloginonce for that agent.
License & Attribution
Licensed under the MIT License. Built on top of perplexity-web-mcp by quequiere.
Available Tools
7 toolscompare_modelsA
Ask one question across 2–5 Perplexity models (running concurrently when multiple PERPLEXITY_PROFILE_DIRS profiles or backend='api' are configured), compare shared citations and agreed/divergent key facts, and return a consolidated Markdown report (spooled to .txt if >= 15000 chars or output_file is set).
Inputs: query (required), models, backend, sources, +4 more.
health_checkA
Quick (~5s) diagnostic check verifying Perplexity authentication, absence of Cloudflare blocks, composer search input, add/sources trigger, model selector hydration, and writable local directories. Saves a diagnostic HTML+PNG snapshot automatically if any check fails.
Inputs: profile.
list_modelsA
List the AI models available on your Perplexity.ai account (excluding unavailable Max-tier models), active and saved default model, and configured browser profile pool status.
Inputs: profile.
loginA
Check if you are authenticated on Perplexity.ai for the default or specified browser profile. If not, opens a visible browser window so you can log in once.
Inputs: profile.
searchB
Search the web using Perplexity.ai with claim-level citation provenance ([1] markers, snippets, dates), optional live claim-source verification (supported/weak/unverified), local caching, cancellation-safe streaming, progress notifications, partial .txt checkpoints, typed error JSON, poolable browser profiles, and optional official Agent API backend. Supports model, thread_url, timeout_seconds (default 900s / max 1800s), profile, backend, verify_claims, no_cache, and output_file / auto .txt spooling (>= 15000 chars).
Inputs: query (required), model, backend, profile, +5 more.
search_advancedA
Search Perplexity.ai with specific source selection (web, academic, social), claim-level citation provenance ([1] markers, snippets, dates), optional live claim-source verification, local caching, cancellation-safe streaming, progress notifications, partial .txt checkpoints, typed error JSON, poolable browser profiles, and optional official Agent API backend.
Inputs: query (required), sources (required), model, backend, +6 more.
set_default_modelA
Set or clear your sticky default Perplexity model (persisted locally). Used automatically by search/search_advanced whenever no model argument is passed.
Inputs: model (required), profile.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes: search, compare_models, health_check, login, list_models, and set_default_model are all separable. The only real overlap is search vs search_advanced, which differ mainly by source selection (web/academic/social), a distinction an agent could plausibly miss. Descriptions help but the boundary is not sharp.
Nearly all names follow a snake_case verb_noun pattern (list_models, set_default_model, search_advanced, health_check, compare_models). The bare verbs 'search' and 'login' are the only deviations, but they remain readable and predictable.
Seven tools is well-scoped for a Perplexity search integration: search paths, model management, diagnostics, auth, and comparison. Each tool maps to a distinct operational need with no filler.
The surface covers search, model management, auth, diagnostics, and cross-model comparison, which is solid for the domain. Minor gaps exist: no tool to list/inspect or resume saved threads despite thread_url being accepted, and no cache-clear or logout counterpart to login.
Maintenance
Related MCP Connectors
Real-time web search, reasoning, and research through Perplexity's API
Playwright browser automation — navigate, click, fill forms, extract, screenshot — 17 agent tools.
Web search, browser automation, scraping, crawling and CAPTCHA solving for AI agents.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to perform web searches and deep research via Perplexity, without API costs, using session-based authentication and multi-account pooling.214MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to control a web browser using Playwright, supporting navigation, interaction, and data extraction through natural language.MIT
- AlicenseNot gradedqualityDmaintenanceEnables browser automation for AI assistants via Playwright, supporting multiple browsers, sessions, and tools for web interaction and testing.984 npmMIT
- FlicenseNot gradedqualityDmaintenanceGives AI agents live research and image generation capabilities by automating a logged-in Perplexity Pro browser session.-