Skip to content
Back to search

perplexity-web-mcp

MCP server for Perplexity that works through your own perplexity.ai web session (no API key)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/h1di--perplexity-web-mcp/badge.svg)](/listings/h1di--perplexity-web-mcp)

HTML

<a href="/listings/h1di--perplexity-web-mcp"><img src="/api/listings/h1di--perplexity-web-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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"`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 129 lines
  1. # perplexity-web-mcp
  2. An MCP server that gives AI assistants Perplexity search through **your own perplexity.ai account**.
  3. It drives a local Chrome with your logged-in web session, so you don't need an API key or API credits.
  4. Your Perplexity subscription limits (Pro Search, Deep Research, etc.) apply as usual.
  5. > **Unofficial.** This project is not affiliated with Perplexity. It uses perplexity.ai's internal web API,
  6. > which can change at any time, and automated use may violate Perplexity's Terms of Service.
  7. > Use it with your own account, for personal use, at your own risk.
  8. ## Tool
  9. `perplexity_search(query, mode="pro", model=None, academic=False)`
  10. | mode | what it does |
  11. |---|---|
  12. | `auto` | fast default answer |
  13. | `pro` | Pro Search (default) |
  14. | `reasoning` | reasoning model |
  15. | `deep_research` | Deep Research: slow and thorough, counts against your daily limit |
  16. `academic=True` searches scholarly sources instead of the general web. `model` lets you pass a raw
  17. Perplexity `model_preference` value if you want a specific model.
  18. The tool returns the answer in Markdown, followed by a numbered list of sources.
  19. ## Requirements
  20. - [uv](https://docs.astral.sh/uv/getting-started/installation/)
  21. - macOS / Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
  22. - Windows (PowerShell): `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
  23. - Google Chrome. On Windows, Microsoft Edge is used if Chrome is not installed.
  24. - A perplexity.ai account (Pro recommended)
  25. ## Install
  26. ### 1. Log in once
  27. This opens a browser window. Sign in to Perplexity, then close the window.
  28. ```sh
  29. uvx --from git+https://github.com/H1di/perplexity-web-mcp perplexity-web-mcp login
  30. ```
  31. If Google sign-in says the browser is not secure, sign in with your email instead (Perplexity sends you a code).
  32. ### 2. Add the server to your MCP client
  33. Use the standard `mcpServers` config:
  34. ```json
  35. {
  36. "mcpServers": {
  37. "perplexity": {
  38. "command": "uvx",
  39. "args": ["--from", "git+https://github.com/H1di/perplexity-web-mcp", "perplexity-web-mcp"]
  40. }
  41. }
  42. }
  43. ```
  44. Restart the client, and the `perplexity_search` tool becomes available.
  45. **If the client can't find `uvx`**, use its full path as `"command"`. This is common with desktop apps on macOS,
  46. which don't inherit your shell `PATH`. To get the full path:
  47. | OS | command | typical result |
  48. |---|---|---|
  49. | macOS | `which uvx` | `/Users/you/.local/bin/uvx` |
  50. | Linux | `which uvx` | `/home/you/.local/bin/uvx` |
  51. | Windows | `where uvx` | `C:\Users\you\.local\bin\uvx.exe` |
  52. In JSON on Windows, escape backslashes: `"command": "C:\\Users\\you\\.local\\bin\\uvx.exe"`.
  53. ## Platform notes
  54. The browser runs in normal (headed) mode, because Cloudflare blocks headless browsers on perplexity.ai.
  55. It starts on the first query and closes after 60 s without queries. How it is kept out of sight depends on the OS:
  56. | OS | behavior |
  57. |---|---|
  58. | 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. |
  59. | macOS | The window is placed off-screen. A Chrome icon appears in the Dock while queries run. |
  60. | Windows | The window is placed off-screen. It may show up in the taskbar while queries run. |
  61. The login window is always visible.
  62. ## Configuration
  63. Set these environment variables in the server's `env` block:
  64. | variable | default | meaning |
  65. |---|---|---|
  66. | `PPLX_PROFILE` | see below | browser profile that stores your login |
  67. | `PPLX_IDLE_CLOSE` | `60` | seconds without queries before the browser closes |
  68. | `PPLX_HIDE` | `1` | set to `0` to show the browser window |
  69. | `PPLX_BROWSER` | `chrome`, then `msedge` | Playwright channel to use: `chrome`, `msedge`, `chrome-beta`, ... |
  70. Default profile location:
  71. - Linux: `~/.local/share/perplexity-mcp/profile`
  72. - macOS: `~/Library/Application Support/perplexity-mcp/profile`
  73. - Windows: `%LOCALAPPDATA%\perplexity-mcp\profile`
  74. If you set `PPLX_PROFILE` or `PPLX_BROWSER`, set the same value when you run `login`.
  75. ## How it works
  76. - The server runs a real (headed) Chrome with a dedicated profile.
  77. - Queries are sent with `fetch()` from inside the perplexity.ai page to the same endpoint the website uses.
  78. The server then parses the streamed response.
  79. - Queries are sent in incognito mode, so they don't appear in your Perplexity history.
  80. ## Troubleshooting
  81. - **"No supported browser found"**: install Google Chrome, or set `PPLX_BROWSER`.
  82. - **"Not logged in"**: your session expired. Run the `login` command again.
  83. - **HTTP 4xx or "Unexpected response"**: Perplexity probably changed its web API. Please open an issue.
  84. - **Hangs on the first query**: Cloudflare may be showing a challenge. Run with `PPLX_HIDE=0` to watch the browser.
  85. ## Development
  86. ```sh
  87. git clone https://github.com/H1di/perplexity-web-mcp && cd perplexity-web-mcp
  88. uv run perplexity-web-mcp login
  89. uv run python -m unittest discover tests
  90. ```
  91. ## License
  92. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.