perplexity-web-mcp
A lightweight MCP (Model Context Protocol) server that enables AI assistants to perform searches on Perplexity.ai through browser automation. No official API key required.
Overview
perplexity-web-mcp bridges your AI assistant (Claude, Cursor, etc.) with Perplexity.ai by automating a real browser session via Playwright. It reads search results directly from the DOM — making it indistinguishable from a real user — and returns the answer text along with cited sources.
Key features
- Login once, search forever — use the
logintool to authenticate once; your session persists across restarts - Lazy browser launch — the browser only opens on the first tool call, not at server startup
- Always visible browser — runs non-headless to bypass Cloudflare's bot detection (the window stays in the background during searches)
- Sources included — returns cited URLs alongside the answer text
- Zero API key — uses your existing Perplexity session (free or Pro)
Installation
Prerequisites:
- Node.js >= 20
- Chromium (via Playwright):
npx playwright install chromium
npx playwright install chromium
That's it — no clone, no build required.
MCP configuration
Claude Code
claude mcp add perplexity-web -- npx perplexity-web-mcp@latest
Claude Desktop / other clients
Add to your MCP config (.claude.json):
{
"mcpServers": {
"perplexity-web": {
"command": "npx",
"args": ["perplexity-web-mcp@latest"]
}
}
}
Optional flag: --timeout=N — max seconds to wait for an answer (default: 20).
To authenticate, ask your AI client to call the login tool once. A Chromium window will open for you to sign in. Your session is persisted in .playwright/profile/ and reused on future runs.
Why is a browser window visible? Perplexity.ai uses Cloudflare Turnstile which blocks headless browsers. The window stays in the background and requires no interaction during normal use.
MCP Tools
`login`
Checks if you are authenticated on Perplexity.ai. If not, opens a browser window so you can log in.
Parameters: none
Returns: A status message — either "Already authenticated" or "Login successful" after the user completes the login flow.
Your session is persisted in
.playwright/profile/— you only need to callloginonce, or after a session expiry.
`search`
Performs a search on Perplexity.ai using default settings and returns the answer with sources. Prefer this for general queries.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
query |
string |
Yes | The search query |
Returns:
The capital of France is Paris...
Sources:
1. [Capital City of France - CountryReports](https://www.countryreports.org/...)
`search_advanced`
Same as search but lets you select which sources Perplexity searches. You can combine multiple sources. Uses browser UI automation to toggle the source checkboxes — more powerful but slightly less resilient to UI changes.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
query |
string |
Yes | The search query |
sources |
string[] |
Yes | One or more sources: web, academic, social |
Example: sources: ["web", "academic"] searches both general web and scholarly articles simultaneously.
Returns: Same format as search.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ AI Client (Claude Desktop / Claude Code / Cursor / ...) │
└────────────────────────┬────────────────────────────────────────┘
│ MCP stdio transport
▼
┌─────────────────────────────────────────────────────────────────┐
│ perplexity-web-mcp (FastMCP server) │
│ │
│ ┌─────────────────┐ ┌──────────────────────────────────────┐ │
│ │ CLI Arguments │ │ MCP Tools │ │
│ │ │ │ │ │
│ │ --timeout=N │ │ login() │ │
│ │ │ │ checks session, opens browser │ │
│ │ │ │ for login if not authenticated │ │
│ │ │ │ │ │
│ │ │ │ search(query, mode?) │ │
│ │ │ │ returns: { answer, sources[] }
Tools 3
loginChecks if you are authenticated on Perplexity.ai and opens a browser window for login if necessary.searchPerforms a search on Perplexity.ai using default settings and returns the answer with sources.search_advancedPerforms a search on Perplexity.ai with selectable source types like web, academic, or social.