Skip to content
Back to search

perplexity-web-api-mcp

πŸ” Perplexity AI MCP without API key

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

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

Install

i

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 Β· 322 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Perplexity Web API MCP Server
  2. <p>
  3. <a href="https://cursor.com/en/install-mcp?name=perplexity-web&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBlcnBsZXhpdHktd2ViLWFwaS1tY3AiXSwiZW52Ijp7IlBFUlBMRVhJVFlfU0VTU0lPTl9UT0tFTiI6IiIsIlBFUlBMRVhJVFlfQ1NSRl9UT0tFTiI6IiJ9fQ==" target="_blank">
  4. <img src="https://custom-icon-badges.demolab.com/badge/Install_in_Cursor-000000?style=for-the-badge&logo=cursor-ai-white" alt="Install in Cursor">
  5. </a>
  6. <a href="https://vscode.dev/redirect/mcp/install?name=perplexity-web&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22perplexity-web-api-mcp%22%5D%2C%22env%22%3A%7B%22PERPLEXITY_SESSION_TOKEN%22%3A%22%22%2C%22PERPLEXITY_CSRF_TOKEN%22%3A%22%22%7D%7D" target="_blank">
  7. <img src="https://custom-icon-badges.demolab.com/badge/Install_in_VS_Code-007ACC?style=for-the-badge&logo=vsc&logoColor=white" alt="Install in VS Code">
  8. </a>
  9. <a href="https://www.npmjs.com/package/perplexity-web-api-mcp" target="_blank">
  10. <img
  11. src="https://img.shields.io/npm/v/perplexity-web-api-mcp?style=for-the-badge&logo=npm&logoColor=white&color=CB3837"
  12. alt="NPM Version" />
  13. </a>
  14. </p>
  15. MCP (Model Context Protocol) server that exposes Perplexity AI search, research, and reasoning capabilities as tools.
  16. ## No API Key Required
  17. This MCP server uses your Perplexity account session directly β€” **no API key needed**.
  18. Perplexity offers a separate [paid API](https://docs.perplexity.ai/guides/pricing) with per-request pricing that is charged independently from your Pro subscription. With this MCP, you don't need to pay for API access β€” your existing Perplexity subscription (or even a free account) is enough.
  19. Simply extract the session tokens from your browser cookies, and you're ready to use Perplexity search, research, and reasoning in your IDE.
  20. ## Tokenless Mode
  21. The server can run **without any authentication tokens**. In this mode:
  22. - Only `perplexity_search` (links only) and `perplexity_ask` (answer with sources) are available β€” `perplexity_research` and `perplexity_reason` require tokens.
  23. - Both tools use the `turbo` model; `PERPLEXITY_ASK_MODEL` and `PERPLEXITY_REASON_MODEL` cannot be set (the server will throw an error if they are).
  24. - File attachments (`files` parameter) are unavailable β€” they require tokens.
  25. To use tokenless mode, simply omit `PERPLEXITY_SESSION_TOKEN` and `PERPLEXITY_CSRF_TOKEN` from your configuration.
  26. For full access to all tools and model selection, provide both tokens as described in the [Configuration](#configuration) section below.
  27. ## Requirements
  28. ### Supported Platforms
  29. - macOS (arm64, x86_64)
  30. - Linux (x86_64, aarch64)
  31. - Windows (x86_64)
  32. ## Configuration
  33. ### Getting Your Tokens
  34. This server requires a Perplexity AI account. You need to extract two authentication tokens from your browser cookies:
  35. 1. Log in to [perplexity.ai](https://www.perplexity.ai) in your browser
  36. 2. Open Developer Tools (F12 or right-click β†’ Inspect)
  37. 3. Go to Application β†’ Cookies β†’ `https://www.perplexity.ai`
  38. 4. Copy the values of:
  39. - `__Secure-next-auth.session-token` β†’ use as `PERPLEXITY_SESSION_TOKEN`
  40. - `next-auth.csrf-token` β†’ use as `PERPLEXITY_CSRF_TOKEN`
  41. ### Environment Variables
  42. - `PERPLEXITY_SESSION_TOKEN` (optional): Perplexity session token (`next-auth.session-token` cookie). Required for `perplexity_research`, `perplexity_reason`, and file attachments.
  43. - `PERPLEXITY_CSRF_TOKEN` (optional): Perplexity CSRF token (`next-auth.csrf-token` cookie). Required for `perplexity_research`, `perplexity_reason`, and file attachments.
  44. - `PERPLEXITY_ASK_MODEL` (optional, requires tokens): Model for `perplexity_ask`.
  45. Valid values:
  46. - `turbo` (default for tokenless)
  47. - `pro-auto` (default for authenticated)
  48. - `sonar`
  49. - `gpt-5.4`
  50. - `claude-4.6-sonnet`
  51. - `nemotron-3-super`
  52. - `PERPLEXITY_REASON_MODEL` (optional, requires tokens): Model for `perplexity_reason`.
  53. Valid values:
  54. - `gemini-3.1-pro` (default)
  55. - `gpt-5.4-thinking`
  56. - `claude-4.6-sonnet-thinking`
  57. - `PERPLEXITY_INCOGNITO` (optional, default: `true`): Whether requests should use Perplexity's incognito mode.
  58. Valid values: `true` or `false`
  59. ### Claude Code
  60. ```bash
  61. claude mcp add perplexity --env PERPLEXITY_SESSION_TOKEN="your-session-token" --env PERPLEXITY_CSRF_TOKEN="your-csrf-token" -- npx -y perplexity-web-api-mcp
  62. ```
  63. ### Cursor, Claude Desktop & Windsurf
  64. I recommend using the one-click install badge at the top of this README for Cursor.
  65. For manual setup, all these clients use the same `mcpServers` format:
  66. | Client | Config File |
  67. |--------|-------------|
  68. | Cursor | `~/.cursor/mcp.json` |
  69. | Claude Desktop | `claude_desktop_config.json` |
  70. | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
  71. ```json
  72. {
  73. "mcpServers": {
  74. "perplexity": {
  75. "command": "npx",
  76. "args": ["-y", "perplexity-web-api-mcp"],
  77. "env": {
  78. "PERPLEXITY_SESSION_TOKEN": "your-session-token",
  79. "PERPLEXITY_CSRF_TOKEN": "your-csrf-token"
  80. }
  81. }
  82. }
  83. }
  84. ```
  85. ### Zed
  86. Add following following to `context_servers` in your [settings file](https://zed.dev/docs/configuring-zed.html#settings-files):
  87. ```json
  88. {
  89. "context_servers": {
  90. "perplexity": {
  91. "command": "npx",
  92. "args": ["-y", "perplexity-web-api-mcp"],
  93. "env": {
  94. "PERPLEXITY_SESSION_TOKEN": "your-session-token",
  95. "PERPLEXITY_CSRF_TOKEN": "your-csrf-token"
  96. }
  97. }
  98. }
  99. }
  100. ```
  101. ### VS Code
  102. I recommend using the one-click install badge at the top of this README for VS Code, or for manual setup, add to `.vscode/mcp.json`:
  103. ```json
  104. {
  105. "servers": {
  106. "perplexity": {
  107. "type": "stdio",
  108. "command": "npx",
  109. "args": ["-y", "perplexity-web-api-mcp"],
  110. "env": {
  111. "PERPLEXITY_SESSION_TOKEN": "your-session-token",
  112. "PERPLEXITY_CSRF_TOKEN": "your-csrf-token"
  113. }
  114. }
  115. }
  116. }
  117. ```
  118. ### Codex
  119. ```bash
  120. codex mcp add perplexity --env PERPLEXITY_SESSION_TOKEN="your-session-token" --env PERPLEXITY_CSRF_TOKEN="your-csrf-token" -- npx -y perplexity-web-api-mcp
  121. ```
  122. ### Building from Source
  123. Source build instructions, including optional cargo features, are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
  124. ### Other MCP Clients
  125. Most clients can be manually configured to use the `mcpServers` wrapper in their configuration file (like Cursor). If your client doesn't work, check its documentation for the correct wrapper format.
  126. ## Docker
  127. A pre-built multi-arch image (`linux/amd64`, `linux/arm64`) is available on Docker Hub:
  128. ```bash
  129. docker run -d \
  130. -p 8080:8080 \
  131. -e PERPLEXITY_SESSION_TOKEN="your-session-token" \
  132. -e PERPLEXITY_CSRF_TOKEN="your-csrf-token" \
  133. mishamyrt/perplexity-web-api-mcp
  134. ```
  135. The container exposes the MCP server via Streamable HTTP at `http://localhost:8080/mcp`.
  136. The Docker image is built with `--features streamable-http`; local/source builds need the same feature if you want HTTP transport.
  137. Configure your MCP client to connect:
  138. ```json
  139. {
  140. "mcpServers": {
  141. "perplexity": {
  142. "url": "http://localhost:8080/mcp"
  143. }
  144. }
  145. }
  146. ```
  147. ### Environment Variables (Docker-specific)
  148. | Variable | Default | Description |
  149. |----------|---------|-------------|
  150. | `MCP_TRANSPORT` | `streamable-http` | Transport mode. `stdio` or `streamable-http` (requires the `streamable-http` cargo feature) |
  151. | `MCP_HOST` | `0.0.0.0` | Host address to bind |
  152. | `MCP_PORT` | `8080` | Port to listen on |
  153. The [authentication tokens, model variables, and incognito flag](#configuration) described above work the same way in Docker.
  154. ## Available Tools
  155. ### `perplexity_search`
  156. Quick web search using the `turbo` model. Returns only links, titles, and snippets β€” no generated answer.
  157. **Best for:** Finding relevant URLs and sources quickly.
  158. **Parameters:**
  159. - `query` (required): The search query or question
  160. - `sources` (optional): Array of sources β€” `"web"`, `"scholar"`, `"social"`. Defaults to `["web"]`
  161. - `language` (optional): Language code, e.g., `"en-US"`. Defaults to `"en-US"`
  162. > File attachments are not supported by this tool.
  163. ### `perplexity_ask`
  164. Ask Perplexity AI a question and get a comprehensive answer with source citations. By default uses the best model (Pro auto mode) when authentication tokens are provided, or `turbo` in tokenless mode. Can be configured via `PERPLEXITY_ASK_MODEL`.
  165. **Best for:** Getting detailed answers to questions with web context.
  166. **Parameters:** Same as `perplexity_search`, plus:
  167. - `files` (optional, requires tokens): Array of file attachments for document analysis. See [File Attachments](#file-attachments).
  168. ### `perplexity_reason`
  169. Advanced reasoning and problem-solving. By default uses Perplexity's `sonar-reasoning` model, but can be configured via `PERPLEXITY_REASON_MODEL`.
  170. **Best for:** Logical problems, complex analysis, decision-making, and tasks requiring step-by-step reasoning.
  171. **Parameters:** Same as `perplexity_ask`.
  172. ### `perplexity_research`
  173. Deep, comprehensive research using Perplexity's sonar-deep-research (`pplx_alpha`) model.
  174. **Best for:** Complex topics requiring detailed investigation, comprehensive reports, and in-depth analysis. Provides thorough analysis with citations.
  175. **Parameters:** Same as `perplexity_ask`.
  176. ## File Attachments
  177. `perplexity_ask`, `perplexity_research`, and `perplexity_reason` accept an optional `files` parameter for document analysis. **Requires authentication tokens.**
  178. Each entry in the `files` array must have:
  179. - `filename` (required): Filename with extension, e.g. `"report.pdf"` or `"notes.txt"`
  180. - `text` (mutually exclusive with `data`): Plain-text file content. Use for `.txt`, `.md`, `.csv`, `.json`, source code, etc.
  181. - `data` (mutually exclusive with `text`): Base64-encoded binary content. Use for `.pdf`, `.docx`, images, etc.
  182. **Example β€” plain text:**
  183. ```json
  184. {
  185. "query": "Summarise the key points",
  186. "files": [
  187. {
  188. "filename": "notes.txt",
  189. "text": "Meeting notes: Q1 revenue up 12%..."
  190. }
  191. ]
  192. }
  193. ```
  194. **Example β€” binary file (PDF):**
  195. ```json
  196. {
  197. "query": "What does this contract say about termination?",
  198. "files": [
  199. {
  200. "filename": "contract.pdf",
  201. "data": "JVBERi0xLjQK..."
  202. }
  203. ]
  204. }
  205. ```
  206. Multiple files can be passed in a single request β€” they are uploaded to Perplexity's storage in parallel before the query is sent.
  207. ## Response Format
  208. `perplexity_search` returns only web results:
  209. ```json
  210. {
  211. "web_results": [
  212. {
  213. "name": "Source name",
  214. "url": "https://example.com",
  215. "snippet": "Source snippet"
  216. }
  217. ]
  218. }
  219. ```
  220. `perplexity_ask`, `perplexity_research`, and `perplexity_reason` return a full response:
  221. ```json
  222. {
  223. "answer": "The generated answer text...",
  224. "web_results": [
  225. {
  226. "name": "Source name",
  227. "url": "https://example.com",
  228. "snippet": "Source snippet"
  229. }
  230. ],
  231. "follow_up": {
  232. "backend_uuid": "uuid-for-follow-up-queries",
  233. "attachments": []
  234. }
  235. }
  236. ```
  237. ## License
  238. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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