perplexity-webui-mcp

<h1 align="">perplexity-webui-mcp</h1>

<p align=""> mcp server for querying perplexity pro via webui session token. </p>

<p align=""> <img src="https://img.shields.io/badge/license-MIT-green" alt="license"> <img src="https://img.shields.io/badge/language-typescript-blue" alt="language"> <img src="https://img.shields.io/badge/npm-perplexity--webui--mcp-orange" alt="npm"> <img src="https://img.shields.io/badge/mcp-sdk-orange" alt="mcp"> <a href="https://github.com/Microck/opencode-studio"><img src="https://img.shields.io/badge/opencode-studio-brown?logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABiElEQVR4nF2Sv0tWcRTGPyeVIpCWwmyJGqQagsqCsL2hhobsD3BvdWhoj%2F6CiIKaoqXBdMjKRWwQgqZ%2BokSvkIhg9BOT9xPn9Vx79cD3cu6953zP8zznCQB1V0S01d3AKeAKcBVYA94DjyJioru2k9SHE%2Bqc%2Bkd9rL7yf7TUm%2BpQ05yPUM%2Bo626Pp%2BqE2q7GGfWrOpjNnWnAOPAGeAK8Bb4U5D3AJ%2BAQsAAMAHfVvl7gIrAf2Kjiz8BZYB3YC%2FwFpoGDwHfgEnA0oU7tgHiheEShyXxY%2FVn%2Fn6ljye8DcBiYAloRcV3tAdrV1xMRG%2Bo94DywCAwmx33AJHASWK7iiAjzNFOBl7WapPYtYdyo8RlLqVpOVPvq9KoH1NUuOneycaRefqnP1ftdUyiOt5KS%2BqLWdDpVzTXMl5It4Jr6u%2BQ%2FnhyBc8C7jpowGxGvmxuPqT9qyYuFIKdP71B8WT3SOKexXLrntvqxq3BefaiuFMQ0wqZftxl3M78MjBasfiDN%2FSAi0kFbtf8ACtKBWZBDoJEAAAAASUVORK5CYII%3D" alt="Add with OpenCode Studio" /></a> </p>

---

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:

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:

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

manual run:

PERPLEXITY_SESSION_TOKEN="your_token_here" npx perplexity-webui-mcp

manual run through a proxy:

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

manual run with flaresolverr:

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)

npm install -g perplexity-webui-mcp

runtime requirement:

uv --version

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

---

manual installation

from source

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):

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 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)

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

{
  "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:

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:

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):

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:

{
  "mcp": {
    "perplexity-webui": {
      "type": "remote",
      "url": "http://<tailscale-ip>:8790/sse",
      "enabled": true,
      "timeout": 600000,
      "oauth": false
    }
  }
}

4. verify:

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

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

---

shoutout

special thanks to henrique-coder/perplexity-webui-scraper for the WebUI reverse-engineering and token CLI workflow that helped this project.