# Perplexity Webui Mcp

> MCP server for querying Perplexity Pro via WebUI session token

- **Type:** MCP server
- **Install:** `agentstack add mcp-microck-perplexity-webui-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Microck](https://agentstack.voostack.com/s/microck)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Microck](https://github.com/Microck)
- **Source:** https://github.com/Microck/perplexity-webui-mcp

## Install

```sh
agentstack add mcp-microck-perplexity-webui-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

perplexity-webui-mcp

  mcp server for querying perplexity pro via webui session token.

  
  
  
  
  

---

## quick start

this package is a local mcp wrapper (stdio transport) that launches the upstream `perplexity-webui-scraper` mcp server via `uvx`.

by default it pins the upstream runner to:

```text
perplexity-webui-scraper[mcp]@git+https://github.com/henrique-coder/perplexity-webui-scraper.git@prod
```

override that only if you need to test a different upstream build:

```bash
PERPLEXITY_UPSTREAM_FROM="perplexity-webui-scraper[mcp]@git+https://github.com/henrique-coder/perplexity-webui-scraper.git@" \
PERPLEXITY_SESSION_TOKEN="your_token_here" \
npx perplexity-webui-mcp
```

manual run:

```bash
PERPLEXITY_SESSION_TOKEN="your_token_here" npx perplexity-webui-mcp
```

manual run through a proxy:

```bash
PERPLEXITY_SESSION_TOKEN="your_token_here" \
PERPLEXITY_PROXY_URL="socks5://127.0.0.1:1080" \
npx perplexity-webui-mcp
```

manual run with flaresolverr:

```bash
docker run -d --name flaresolverr -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest

PERPLEXITY_SESSION_TOKEN="your_token_here" \
PERPLEXITY_FLARESOLVERR_URL="http://127.0.0.1:8191" \
npx perplexity-webui-mcp
```

> **important:** this uses perplexity's internal webui api with a session cookie. for personal/local tinkering only - not affiliated with perplexity ai.

---

### overview

perplexity-webui-mcp is a local stdio mcp wrapper that launches the upstream `perplexity-webui-scraper` mcp server through `uvx`. this keeps the package on npm while using the upstream webui implementation for browser impersonation, retry logic, model-specific tools, and token tooling.

---

### quick installation

paste this into your llm agent session:

```
Install and configure perplexity-webui-mcp by following the instructions here:
https://raw.githubusercontent.com/Microck/perplexity-webui-mcp/refs/heads/master/INSTALL.md
```

**npm (recommended)**

```bash
npm install -g perplexity-webui-mcp
```

runtime requirement:

```bash
uv --version
```

if `uv` is missing, install it from https://docs.astral.sh/uv/getting-started/installation/

---

### manual installation

**from source**

```bash
git clone https://github.com/Microck/perplexity-webui-mcp.git
cd perplexity-webui-mcp
npm install
npm run build
```

---

### getting your session token

**fastest method (automatic via CLI):**

```bash
uvx --with rich --from "perplexity-webui-scraper@git+https://github.com/henrique-coder/perplexity-webui-scraper.git@prod" get-perplexity-session-token
```

this interactive CLI asks for your email, handles OTP/magic-link verification, and prints the session token.

you can run that command from any directory.

**manual method (browser):**

1. open [perplexity.ai](https://www.perplexity.ai) in your browser and log in
2. open devtools (f12 or cmd+opt+i)
3. go to **application** > **cookies** > `https://www.perplexity.ai`
4. copy the value of `__Secure-next-auth.session-token`

> powered by token extraction flow from: https://github.com/henrique-coder/perplexity-webui-scraper

---

### configuration

because this server uses `stdio`, you configure it as a local command and pass the token via `env`.

proxy support:
- standard proxy env vars already pass through: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and their lowercase variants
- for a simpler single-value setup, set `PERPLEXITY_PROXY_URL`; the wrapper expands it into the standard proxy env vars before launching the upstream MCP server
- optional bypass list: `PERPLEXITY_NO_PROXY`
- if perplexity keeps returning cloudflare challenge pages, set `PERPLEXITY_FLARESOLVERR_URL` to a running flaresolverr instance. the wrapper solves `https://www.perplexity.ai/search/new`, injects the returned cookies into the upstream `curl_cffi` session, and stops forwarding the standard proxy env vars in that mode
- optional flaresolverr overrides:
  - `PERPLEXITY_FLARESOLVERR_SOLVE_URL` - alternate url to solve first. default: `https://www.perplexity.ai/search/new`
  - `PERPLEXITY_FLARESOLVERR_MAX_TIMEOUT` - flaresolverr solve timeout in milliseconds. default: `60000`

note: deep research can take longer than 60 seconds. if your client supports it, set a higher `timeout` (example: 10 minutes).

**mcp client config (claude desktop, opencode, etc)**

```json
{
  "mcpServers": {
    "perplexity": {
      "command": "perplexity-webui-mcp",
      "timeout": 600000,
      "env": {
        "PERPLEXITY_SESSION_TOKEN": "your_session_token_here",
        "PERPLEXITY_FLARESOLVERR_URL": "http://127.0.0.1:8191"
      }
    }
  }
}
```

**from source**

```json
{
  "mcpServers": {
    "perplexity": {
      "command": "node",
      "args": ["/path/to/perplexity-webui-mcp/dist/index.js"],
      "timeout": 600000,
      "env": {
        "PERPLEXITY_SESSION_TOKEN": "your_session_token_here",
        "PERPLEXITY_FLARESOLVERR_URL": "http://127.0.0.1:8191"
      }
    }
  }
}
```

### using flaresolverr when cloudflare blocks your host

start flaresolverr:

```bash
docker run -d --name flaresolverr -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest
curl http://127.0.0.1:8191/
```

then point the wrapper at it:

```bash
PERPLEXITY_SESSION_TOKEN="your_token_here" \
PERPLEXITY_FLARESOLVERR_URL="http://127.0.0.1:8191" \
npx perplexity-webui-mcp
```

flaresolverr mode:
- the wrapper solves the cloudflare wall in flaresolverr first, then injects the returned cookies into the upstream session
- the wrapper does not forward `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, or `NO_PROXY` to the upstream process in this mode because the solved cookies need to stay tied to the flaresolverr browser route
- if flaresolverr itself needs a proxy, configure that on the flaresolverr side instead of on `perplexity-webui-mcp`

### remote deployment over tailscale (optional)

if your cloud machine gets blocked by cloudflare but your home machine works, run the upstream mcp server on the home machine and connect to it from opencode as a remote mcp.

1) copy templates from this repo:
- `deploy/systemd/perplexity-webui-mcp.env.example`
- `deploy/systemd/perplexity-webui-mcp-sse.sh`
- `deploy/systemd/perplexity-webui-mcp.service`

2) install and enable service on the home machine (user service):

```bash
mkdir -p ~/.config ~/.config/systemd/user ~/.local/bin
cp deploy/systemd/perplexity-webui-mcp.env.example ~/.config/perplexity-webui-mcp.env
cp deploy/systemd/perplexity-webui-mcp-sse.sh ~/.local/bin/perplexity-webui-mcp-sse.sh
cp deploy/systemd/perplexity-webui-mcp.service ~/.config/systemd/user/perplexity-webui-mcp.service
chmod 600 ~/.config/perplexity-webui-mcp.env
chmod 755 ~/.local/bin/perplexity-webui-mcp-sse.sh
systemctl --user daemon-reload
systemctl --user enable --now perplexity-webui-mcp.service
```

3) point opencode (cloud host) to the tailscale endpoint:

```json
{
  "mcp": {
    "perplexity-webui": {
      "type": "remote",
      "url": "http://:8790/sse",
      "enabled": true,
      "timeout": 600000,
      "oauth": false
    }
  }
}
```

4) verify:

```bash
opencode mcp list
```

---

### features

| tool | description |
|------|-------------|
| `pplx_ask` | best-model query (auto model selection) |
| `pplx_deep_research` | deep research mode |
| `pplx_sonar` | sonar model |
| `pplx_gpt54` / `pplx_gpt54_thinking` | gpt-5.4 variants |
| `pplx_claude_o46` / `pplx_claude_o46_think` | claude opus 4.6 variants |
| `pplx_claude_s46` / `pplx_claude_s46_think` | claude sonnet 4.6 variants |
| `pplx_gemini31_pro` / `pplx_gemini31_pro_think` | gemini 3.1 pro variants |
| `pplx_gemini_flash` / `pplx_gemini_flash_think` | gemini flash variants |
| `pplx_grok41` / `pplx_grok41_think` | grok 4.1 variants |
| `pplx_nemotron3_super_think` | nemotron 3 super thinking |

all upstream model tools support `source_focus` values: `web`, `academic`, `social`, `finance`, `all`.

### how this differs from v1.0.0

- old v1.0.0: one custom tool (`perplexity_search`) implemented in local TypeScript HTTP logic.
- current: delegates to upstream `perplexity-webui-scraper` MCP, exposing the full upstream model-specific toolset.
- result: significantly better compatibility with Perplexity anti-bot protections.

---

### troubleshooting

| problem | solution |
|---------|----------|
| **token invalid / 401** | get a fresh token from browser cookies |
| **`uvx` not found** | install uv (`uv --version` should work) |
| **no answer returned** | check rate limits or whether your account can access the selected model |
| **clarifying questions error** | deep research retries once with recommended/default clarification choices; if this still appears, Perplexity rejected the skip and needs a more specific query |
| **cloudflare challenge / `Just a moment...`** | run flaresolverr and set `PERPLEXITY_FLARESOLVERR_URL=http://127.0.0.1:8191` |
| **timeout** | deep research can take several minutes - be patient |

### verify both modes quickly

```bash
PERPLEXITY_SESSION_TOKEN="your_token_here" npm run self-test
```

this checks both:
- regular search (`best`)
- deep research (`deep-research`)

and prints pass/fail per mode.

---

### project structure

```
perplexity-webui-mcp/
├── deploy/
│   └── systemd/
│       ├── perplexity-webui-mcp.env.example
│       ├── perplexity-webui-mcp-sse.sh
│       └── perplexity-webui-mcp.service
├── src/
│   └── index.ts      # proxy launcher for upstream MCP
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── LICENSE
├── INSTALL.md
└── README.md
```

---

### license

mit

---

### author

[Microck](https://github.com/Microck)

---

### shoutout

special thanks to [henrique-coder/perplexity-webui-scraper](https://github.com/henrique-coder/perplexity-webui-scraper) for the WebUI reverse-engineering and token CLI workflow that helped this project.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Microck](https://github.com/Microck)
- **Source:** [Microck/perplexity-webui-mcp](https://github.com/Microck/perplexity-webui-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-microck-perplexity-webui-mcp
- Seller: https://agentstack.voostack.com/s/microck
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.