Skip to main content
Glama
perplexity-web-mcp

perplexity-web-mcp

by H1di
README.md
# 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.

## Requirements

- [uv](https://docs.astral.sh/uv/getting-started/installation/)
  - 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.

```sh
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:

```json
{
  "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

```sh
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

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