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 login tool 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 call login once, 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[] }    │ │
│  └────────┬────────┘   └──────────────┬───────────────────────┘ │
│           │                           │                         │
│           ▼                           ▼                         │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  Browser Manager (Playwright, always visible)              │ │
│  │                                                            │ │
│  │  (browser launches lazily on first tool call)              │ │
│  │                                                            │ │
│  │  login()                                                   │ │
│  │    ├── GET /api/auth/session                               │ │
│  │    │    ├── active ──► "already authenticated"             │ │
│  │    │    └── none   ──► open browser, wait for user login   │ │
│  │                                                            │ │
│  │  search(query)                                             │ │
│  │    ├── open new tab, navigate to perplexity.ai             │ │
│  │    ├── type query in search box                            │ │
│  │    ├── wait for answer to complete (DOM signal)            │ │
│  │    ├── extract answer text from DOM                        │ │
│  │    ├── extract cited sources                               │ │
│  │    └── close tab                                           │ │
│  │                                                            │ │
│  │  search_advanced(query, sources[])                         │ │
│  │    ├── open new tab, navigate to perplexity.ai             │ │
│  │    ├── open "+" menu → "Connecteurs et sources"            │ │
│  │    ├── toggle source checkboxes to match requested sources │ │
│  │    ├── type query, wait for answer, extract DOM            │ │
│  │    └── close tab                                           │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                         │
                         ▼
              ┌──────────────────────┐
              │   perplexity.ai      │
              │  (real browser req)  │
              └──────────────────────┘

---

Development

# Run in development mode (hot reload)
npm run dev

# Build
npm run build

# Lint
npm run lint

# Type check
npm run typecheck

Testing locally

See docs/testing.md for a full step-by-step guide covering:

• First-time authentication flow
• Persistent session verification
• Integration with Claude Code / Claude Desktop

---

How it works

1. Lazy browser launch — the browser only opens when the first tool (login or search) is called, not at server startup.
2. Login — the login tool calls GET /api/auth/session to check the persisted session. If no session is found, a browser window opens and the server waits for the user to log in (up to 5 minutes).
3. Search — the search tool opens a new tab, navigates to perplexity.ai, types the query, and waits for Perplexity's answer to complete (detected via a DOM signal — the "N sources" button appearing).
4. Search Advanced — search_advanced does the same but first opens the source selector menu and toggles the requested sources (identified by their SVG icon IDs, which are locale-independent).
5. Extraction — the answer and sources are extracted from the DOM and returned as text to the MCP client. The tab is then closed.
6. Visible browser — the browser always runs non-headless to pass Cloudflare's Turnstile bot detection, which reliably blocks headless Chromium regardless of stealth patches.

---

Limitations

• Depends on Perplexity.ai's DOM structure — may break if they update their UI
• Rate limiting applies as per Perplexity's standard usage policies
• A visible browser window is always present (required to bypass Cloudflare Turnstile)
• Pro features (deeper research, Claude model) require an authenticated Pro account

---

Contributing

Contributions are welcome! Please open an issue before submitting large PRs.

1. Fork the repo
2. Create a branch: git checkout -b feat/my-feature
3. Commit your changes
4. Open a Pull Request

---

License

MIT — see LICENSE for details.

---

Disclaimer

This project automates a browser session for personal use. It is not affiliated with Perplexity AI, Inc. Use responsibly and in accordance with Perplexity's Terms of Service.