Skip to main content
Glama
perplexity-web-mcp

perplexity-web-mcp

by H1di

perplexity-web-mcp

An MCP server that gives AI assistants Perplexity search through your own perplexity.ai account. It drives a local Chrome with your logged-in web session, so you don't need an API key or API credits. Your Perplexity subscription limits (Pro Search, Deep Research, etc.) apply as usual.

Unofficial. This project is not affiliated with Perplexity. It uses perplexity.ai's internal web API, which can change at any time, and automated use may violate Perplexity's Terms of Service. Use it with your own account, for personal use, at your own risk.

Tool

perplexity_search(query, mode="pro", model=None, academic=False)

mode

what it does

auto

fast default answer

pro

Pro Search (default)

reasoning

reasoning model

deep_research

Deep Research: slow and thorough, counts against your daily limit

academic=True searches scholarly sources instead of the general web. model lets you pass a raw Perplexity model_preference value if you want a specific model. The tool returns the answer in Markdown, followed by a numbered list of sources.

Related MCP server: Perplexity MCP

Requirements

  • uv

    • macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

    • Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  • Google Chrome. On Windows, Microsoft Edge is used if Chrome is not installed.

  • A perplexity.ai account (Pro recommended)

Install

1. Log in once

This opens a browser window. Sign in to Perplexity, then close the window.

uvx --from git+https://github.com/H1di/perplexity-web-mcp perplexity-web-mcp login

If Google sign-in says the browser is not secure, sign in with your email instead (Perplexity sends you a code).

2. Add the server to your MCP client

Use the standard mcpServers config:

{
  "mcpServers": {
    "perplexity": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/H1di/perplexity-web-mcp", "perplexity-web-mcp"]
    }
  }
}

Restart the client, and the perplexity_search tool becomes available.

If the client can't find uvx, use its full path as "command". This is common with desktop apps on macOS, which don't inherit your shell PATH. To get the full path:

OS

command

typical result

macOS

which uvx

/Users/you/.local/bin/uvx

Linux

which uvx

/home/you/.local/bin/uvx

Windows

where uvx

C:\Users\you\.local\bin\uvx.exe

In JSON on Windows, escape backslashes: "command": "C:\\Users\\you\\.local\\bin\\uvx.exe".

Platform notes

The browser runs in normal (headed) mode, because Cloudflare blocks headless browsers on perplexity.ai. It starts on the first query and closes after 60 s without queries. How it is kept out of sight depends on the OS:

OS

behavior

Linux

With Xvfb installed (Arch: xorg-server-xvfb, Debian/Ubuntu: xvfb, Fedora: xorg-x11-server-Xvfb), the browser runs on an invisible virtual display. Without it, the window is visible.

macOS

The window is placed off-screen. A Chrome icon appears in the Dock while queries run.

Windows

The window is placed off-screen. It may show up in the taskbar while queries run.

The login window is always visible.

Configuration

Set these environment variables in the server's env block:

variable

default

meaning

PPLX_PROFILE

see below

browser profile that stores your login

PPLX_IDLE_CLOSE

60

seconds without queries before the browser closes

PPLX_HIDE

1

set to 0 to show the browser window

PPLX_BROWSER

chrome, then msedge

Playwright channel to use: chrome, msedge, chrome-beta, ...

Default profile location:

  • Linux: ~/.local/share/perplexity-mcp/profile

  • macOS: ~/Library/Application Support/perplexity-mcp/profile

  • Windows: %LOCALAPPDATA%\perplexity-mcp\profile

If you set PPLX_PROFILE or PPLX_BROWSER, set the same value when you run login.

How it works

  • The server runs a real (headed) Chrome with a dedicated profile.

  • Queries are sent with fetch() from inside the perplexity.ai page to the same endpoint the website uses. The server then parses the streamed response.

  • Queries are sent in incognito mode, so they don't appear in your Perplexity history.

Troubleshooting

  • "No supported browser found": install Google Chrome, or set PPLX_BROWSER.

  • "Not logged in": your session expired. Run the login command again.

  • HTTP 4xx or "Unexpected response": Perplexity probably changed its web API. Please open an issue.

  • Hangs on the first query: Cloudflare may be showing a challenge. Run with PPLX_HIDE=0 to watch the browser.

Development

git clone https://github.com/H1di/perplexity-web-mcp && cd perplexity-web-mcp
uv run perplexity-web-mcp login
uv run python -m unittest discover tests

License

MIT

Available Tools

1 tool

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 1 tool

    Disambiguation5/5

    There is only one tool, so there is no possibility of misselection between competing tools. The single tool's purpose (web search with Perplexity) is unambiguous, with its modality variants folded into a `mode` argument rather than separate tools.

    Naming Consistency5/5

    A single, clearly readable snake_case name (`perplexity_search`) that namespaces the provider and the action. There is no second naming convention to conflict with it.

    Tool Count3/5

    One tool is a thin surface for a server that exposes four distinct search modes plus model overrides and academic filtering. Consolidating is reasonable, but the result sits at the low end of what an agent would expect from a dedicated search server.

    Completeness4/5

    For a search-and-answer domain, a single entry point that returns a cited answer covers the core workflow. Minor gaps remain: no conversation/follow-up continuation, no citation or source retrieval, and no way to poll or resume the slow `deep_research` mode.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI-powered web research using your existing Perplexity Pro subscription, providing tools for search, follow-up conversations, and thread management through the Model Context Protocol.
      4
      1,201 PyPI
      24
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to perform web searches and deep research via Perplexity, without API costs, using session-based authentication and multi-account pooling.
      2
      15
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides AI-powered research capabilities through Perplexity's web interface, enabling web search, deep research, chat, and documentation retrieval without API keys.
      8
      GPL 3.0