Skip to main content
Glama
quequiere

perplexity-web-mcp

by quequiere
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

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.

License: MIT TypeScript MCP

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)

Related MCP server: Perplexity MCP Server

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.

Available Tools

3 tools
loginA

Check if you are authenticated on Perplexity.ai. If not, opens a browser window so you can log in.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors (authentication check, browser opening) without annotations, but could detail post-login behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, front-loaded sentence with no wasted words, efficiently conveying purpose and action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers core functionality well; lacks detail on return value or post-login state, but adequate for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters, so baseline 4 applies; description adds no parameter info but doesn't need to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool checks authentication and optionally opens a browser for login, distinguishing it from sibling search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes when to use (to check/login) and what happens next, though no explicit when-not or alternatives are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_advancedA

Search Perplexity.ai with specific source selection. Lets you combine multiple sources (e.g. web + academic). Use this when source control matters; prefer search for general queries.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe search query
sourcesYesSources to search: 'web' (general web), 'academic' (scholarly articles), 'social' (Reddit & forums). Can combine multiple.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It correctly describes the operation as a search, implying non-destructive behavior. While it doesn't detail auth, rate limits, or output format, the core behavior is transparent. A small deduction for missing details that could be useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences that front-load purpose and usage guidelines. Every sentence adds value with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (two required parameters, no output schema, no nested objects), the description adequately covers its function and when to use it. It is complete for an AI agent to decide and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters have schema descriptions, providing 100% coverage. The description reinforces the ability to combine sources (e.g., web + academic), which adds some context but does not significantly enhance understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches Perplexity.ai with specific source selection, and distinguishes from the sibling 'search' tool by noting that 'search' is preferred for general queries. This provides a specific verb-resource pair with differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use this tool ('when source control matters') and when not to ('prefer `search` for general queries'), along with an example of combining sources. This is excellent guidance for an AI agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv1.1.1
    • First observedlogin
    • First observedsearch
    • First observedsearch_advanced
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose: login handles authentication, search performs general queries with default settings, and search_advanced offers source control. The descriptions explicitly differentiate when to use each, eliminating ambiguity.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with simple verbs (login, search) and a descriptive variant (search_advanced). The naming is predictable and logical.

Tool Count4/5

With only 3 tools, the server is minimal but appropriately scoped for its purpose of providing Perplexity AI search capabilities. The count is on the low end but still reasonable and focused.

Completeness4/5

The tool set covers the core workflow: authentication (login) and two search modes (general and advanced). This is sufficient for most use cases; missing features like result filtering or account management are not critical gaps.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Perplexity AI MCP Server

    mkusaka
    A
    license
    B
    quality
    D
    maintenance
    An MCP server integrating Perplexity AI's API to offer advanced search capabilities with support for multiple models and result configuration.
    1
    1,014
    1
    MIT

  • Perplexity MCP Server

    RossH121
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that enables Claude to perform web searches using Perplexity's API with intelligent model selection based on query intent and support for domain and recency filtering.
    6
    4
    MIT

  • MCP Perplexity Pro

    cfdude
    A
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive MCP server that provides intelligent access to Perplexity AI's search and reasoning models with automatic model selection, conversation management, and project-aware storage. Supports real-time search, deep research, chat sessions, and async operations for complex queries.
    29
    3
    MIT

  • PPX-MCP

    Mahii1972
    A
    license
    A
    quality
    D
    maintenance
    An unofficial MCP server for Perplexity AI that leverages Pro subscriptions and browser cookies to enable real-time web searches and model selection without an API key. It provides tools for performing queries, listing available models, and automating the login process to manage authentication.
    4
    25
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/quequiere/perplexity-web-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server