Skip to content
Back to search

perplexity-mcp-server

SkillGitHubIncomplete

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/perplexityai--modelcontextprotocol/badge.svg)](/listings/perplexityai--modelcontextprotocol)

HTML

<a href="/listings/perplexityai--modelcontextprotocol"><img src="/api/listings/perplexityai--modelcontextprotocol/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.

If you are running this server at work—especially behind a company firewall or proxy—you may need to tell the program how to send its internet traffic through your network's proxy. Follow these steps:

**1. Get your proxy details**

- Ask your IT department for your HTTPS proxy address and port. - You may also need a username and password.

**2. Set the proxy environment variable**

The easiest and most reliable way for Perplexity MCP is to use `PERPLEXITY_PROXY`. For example:

export PERPLEXITY_PROXY=https://your-proxy-host:8080

If your proxy needs a username and password, use:

export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080

**3. Alternate: Standard environment variables**

If you'd rather use the standard variables, we support `HTTPS_PROXY` and `HTTP_PROXY`.

> [!NOTE] > The server checks proxy settings in this order: `PERPLEXITY_PROXY` → `HTTPS_PROXY` → `HTTP_PROXY`. If none are set, it connects directly to the internet. > URLs must include `https://`. Typical ports are `8080`, `3128`, and `80`.

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.

.claude-plugin/marketplace.json · Manifest · 49 lines

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

  1. {
  2. "name": "perplexity-mcp-server",
  3. "owner": {
  4. "name": "Perplexity AI",
  5. "email": "api@perplexity.ai"
  6. },
  7. "metadata": {
  8. "description": "Official Perplexity AI plugin providing real-time web search, reasoning, and research capabilities",
  9. "version": "1.4.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "perplexity",
  14. "source": "./",
  15. "description": "Real-time web search, reasoning, and research through Perplexity's API",
  16. "version": "1.4.0",
  17. "author": {
  18. "name": "Perplexity AI",
  19. "email": "api@perplexity.ai"
  20. },
  21. "homepage": "https://docs.perplexity.ai/guides/mcp-server",
  22. "repository": "https://github.com/perplexityai/modelcontextprotocol",
  23. "license": "MIT",
  24. "keywords": [
  25. "mcp",
  26. "search",
  27. "web-search",
  28. "perplexity",
  29. "research",
  30. "reasoning",
  31. "ai"
  32. ],
  33. "category": "productivity",
  34. "strict": false,
  35. "mcpServers": {
  36. "perplexity": {
  37. "type": "stdio",
  38. "command": "npx",
  39. "args": ["-y", "@perplexity-ai/mcp-server"],
  40. "env": {
  41. "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}",
  42. "PERPLEXITY_TIMEOUT_MS": "${PERPLEXITY_TIMEOUT_MS:-600000}"
  43. }
  44. }
  45. }
  46. }
  47. ]
  48. }
README.md · README · 216 lines

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

  1. # Perplexity API Platform MCP Server
  2. [![Install in Cursor](https://custom-icon-badges.demolab.com/badge/Install_in_Cursor-000000?style=for-the-badge&logo=cursor-ai-white)](https://cursor.com/install-mcp?name=perplexity&config=eyJ1cmwiOiJodHRwczovL2FwaS5wZXJwbGV4aXR5LmFpL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciBZT1VSX0FQSV9LRVkifX0%3D)
  3. &nbsp;
  4. [![Install in VS Code](https://custom-icon-badges.demolab.com/badge/Install_in_VS_Code-007ACC?style=for-the-badge&logo=vsc&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=perplexity&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.perplexity.ai%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24%7Binput%3Aperplexity-api-key%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22perplexity-api-key%22%2C%22description%22%3A%22Perplexity%20API%20Key%22%2C%22password%22%3Atrue%7D%5D)
  5. &nbsp;
  6. [![Add to Kiro](https://img.shields.io/badge/Add_to_Kiro-9046FF?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTkxIiBoZWlnaHQ9IjIyNi44MTQiIHZpZXdCb3g9IjAgMCAxOTEgMjI2LjgxNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMzUuNjA5IDE3My4xNjVjLTIzLjExMSA1MS4yMzUgMjYuMTA2IDY0LjA2OCA2Mi4zOTYgMzQuMTA2IDEwLjY2IDMzLjYwNSA1MC42OTggOC41MzQgNjUuMDU5LTE3LjUxMSAzMS42MzQtNTcuMzgzIDE4Ljg2Mi0xMTUuOTM3IDE1LjU3OS0xMjguMDE3LTIyLjUwMi04Mi4zNTctMTM0LjkyOS04Mi40MjktMTU0LjI4MS40MTgtNC41MjMgMTQuNTA1LTQuNTk1IDMxLjAwMy03LjE2MSA0OC4xMzItMS4yOSA4LjYzMS0yLjE5OCAxNC4xNDUtNS41MzkgMjMuMjMtMS45MjEgNS4yMTgtNC41NTkgOS44NDktOC43MTQgMTcuNjY2LTguMjEzIDEyLjU0NS4xNTUgMzguMiAzMi42NSAyMi4wMDF6IiBmaWxsPSIjZmZmIi8+PHBhdGggZD0iTTEwMi42MDMgOTYuODk4Yy05LjIyOSAwLTEwLjYxMy0xMS4wMzEtMTAuNjEzLTE3LjU5NyAwLTUuOTMyIDEuMDc0LTEwLjY0OSAzLjA2Ny0xMy42NDRhOC41OCA4LjU4IDAgMCAxIDcuNTIxLTMuOTY0YzMuMjM2IDAgNi4wMDQgMS4zNjIgNy45NjEgNC4wMzYgMi4yMDkgMy4wNDUgMy4zOTEgNy43NTkgMy4zOTEgMTMuNTg2IDAgMTEuMDE3LTQuMjM4IDE3LjU5Ny0xMS4zNDEgMTcuNTk3em0zNy45NDggMGMtOS4yNCAwLTEwLjYyNC0xMS4wMzEtMTAuNjI0LTE3LjU5NyAwLTUuOTMyIDEuMDc0LTEwLjY0OSAzLjA4MS0xMy42NDRhOC41OCA4LjU4IDAgMCAxIDcuNTIxLTMuOTY0IDkuNTEgOS41MSAwIDAgMSA3Ljk1IDQuMDM2YzIuMjIgMy4wNDUgMy40MDIgNy43NTkgMy40MDIgMTMuNTg2IDAgMTEuMDE3LTQuMjM4IDE3LjU5Ny0xMS4zNDEgMTcuNTk3eiIgZmlsbD0iIzAwMCIvPlw8L3N2Zz4=&logoColor=white)](https://kiro.dev/launch/mcp/add?name=perplexity&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40perplexity-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22PERPLEXITY_API_KEY%22%3A%22your_key_here%22%7D%7D)
  7. &nbsp;
  8. [![npm version](https://img.shields.io/npm/v/%40perplexity-ai%2Fmcp-server?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@perplexity-ai/mcp-server)
  9. The official MCP server implementation for the Perplexity API Platform, providing AI assistants with real-time web search, reasoning, and research capabilities through the [Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart) and the Search API.
  10. ## Remote MCP Server
  11. The remote MCP server is hosted by Perplexity and is the easiest way to get started: same tools, nothing to install or update. The Cursor and VS Code buttons at the top of this page connect to it with one click. If your MCP client does not support remote servers yet, skip to the [local server](#local-mcp-server) setup below. Connect over Streamable HTTP with your [Perplexity API key](https://console.perplexity.ai):
  12. ```
  13. https://api.perplexity.ai/mcp
  14. ```
  15. For Claude Code:
  16. ```bash
  17. claude mcp add --transport http perplexity https://api.perplexity.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"
  18. ```
  19. See the [MCP integration docs](https://docs.perplexity.ai/docs/getting-started/integrations/mcp-server) for manual Cursor/VS Code configuration, usage from the Anthropic API, and setup for other clients.
  20. ## Local MCP Server
  21. ### Get Your API Key
  22. 1. Get your Perplexity API Key from the [API Portal](https://console.perplexity.ai)
  23. 2. Replace `your_key_here` in the configurations below with your API key
  24. 3. (Optional) Set timeout: `PERPLEXITY_TIMEOUT_MS=600000` (default: 5 minutes)
  25. 4. (Optional) Set custom base URL: `PERPLEXITY_BASE_URL=https://your-custom-url.com` (default: https://api.perplexity.ai)
  26. 5. (Optional) Set log level: `PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR` (default: ERROR)
  27. ### Claude Code
  28. ```bash
  29. claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
  30. ```
  31. Or install via plugin:
  32. ```bash
  33. export PERPLEXITY_API_KEY="your_key_here"
  34. claude
  35. # Then run: /plugin marketplace add perplexityai/modelcontextprotocol
  36. # Then run: /plugin install perplexity
  37. ```
  38. ### Codex
  39. ```bash
  40. codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
  41. ```
  42. ### Agent Plugins
  43. This repository is packaged as an [Agent Plugin](https://agent-plugins.org), so clients that support the standard can install it directly from this repository. The Agent Plugins format does not carry secrets, so set the `PERPLEXITY_API_KEY` environment variable through your client's plugin or MCP settings.
  44. ### Other MCP Clients
  45. Most clients can be configured manually using the same `mcpServers` wrapper in their client config (as shown for Cursor). If a client has a different schema, check its docs for the exact wrapper format.
  46. For manual setup, these clients all use the same `mcpServers` structure:
  47. | Client | Config File |
  48. |--------|-------------|
  49. | Cursor | `~/.cursor/mcp.json` |
  50. | Claude Desktop | `claude_desktop_config.json` |
  51. | Kiro | `.kiro/settings/mcp.json` |
  52. | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
  53. | VS Code | `.vscode/mcp.json` |
  54. ```json
  55. {
  56. "mcpServers": {
  57. "perplexity": {
  58. "command": "npx",
  59. "args": ["-y", "@perplexity-ai/mcp-server"],
  60. "env": {
  61. "PERPLEXITY_API_KEY": "your_key_here"
  62. }
  63. }
  64. }
  65. }
  66. ```
  67. ### Proxy Setup (For Corporate Networks)
  68. If you are running this server at work—especially behind a company firewall or proxy—you may need to tell the program how to send its internet traffic through your network's proxy. Follow these steps:
  69. **1. Get your proxy details**
  70. - Ask your IT department for your HTTPS proxy address and port.
  71. - You may also need a username and password.
  72. **2. Set the proxy environment variable**
  73. The easiest and most reliable way for Perplexity MCP is to use `PERPLEXITY_PROXY`. For example:
  74. ```bash
  75. export PERPLEXITY_PROXY=https://your-proxy-host:8080
  76. ```
  77. If your proxy needs a username and password, use:
  78. ```bash
  79. export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080
  80. ```
  81. **3. Alternate: Standard environment variables**
  82. If you'd rather use the standard variables, we support `HTTPS_PROXY` and `HTTP_PROXY`.
  83. > [!NOTE]
  84. > The server checks proxy settings in this order: `PERPLEXITY_PROXY` → `HTTPS_PROXY` → `HTTP_PROXY`. If none are set, it connects directly to the internet.
  85. > URLs must include `https://`. Typical ports are `8080`, `3128`, and `80`.
  86. ### Self-Hosted HTTP Mode
  87. For cloud or shared deployments, run the server in HTTP mode.
  88. #### Environment Variables
  89. | Variable | Description | Default |
  90. |----------|-------------|---------|
  91. | `PERPLEXITY_API_KEY` | Your Perplexity API key | *Required* |
  92. | `PERPLEXITY_BASE_URL` | Custom base URL for API requests | `https://api.perplexity.ai` |
  93. | `PORT` | HTTP server port | `8080` |
  94. | `BIND_ADDRESS` | Network interface to bind to. Defaults to loopback. Set to `0.0.0.0` to expose on all interfaces. | `127.0.0.1` |
  95. | `ALLOWED_ORIGINS` | CORS origins (comma-separated). Defaults to empty (no cross-origin browser requests). Set to an explicit allowlist (e.g. `https://app.example.com`) or to `*` to allow any origin. | *(empty)* |
  96. | `ALLOWED_HOSTS` | Additional `Host` header values to accept (comma-separated). Loopback hosts on `PORT` are always allowed. Add the public hostname when binding to `0.0.0.0`. | *(loopback only)* |
  97. #### Docker
  98. ```bash
  99. docker build -t perplexity-mcp-server .
  100. docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server
  101. ```
  102. #### Node.js
  103. ```bash
  104. export PERPLEXITY_API_KEY=your_key_here
  105. npm install && npm run build && npm run start:http
  106. ```
  107. The server will be accessible at `http://localhost:8080/mcp`
  108. ## Available Tools
  109. ### **perplexity_search**
  110. Search results include publication and last-updated dates when available. Missing or null dates are omitted from the formatted output.
  111. Direct web search using the Perplexity Search API. Returns ranked search results with metadata, perfect for finding current information. Supports recency filters (`search_recency_filter`), domain restrictions (`search_domain_filter`), and [Fast Search](https://docs.perplexity.ai/docs/search/fast-search) (`search_type: "fast"`) for lower latency and cost.
  112. ### **perplexity_ask**
  113. General-purpose conversational AI with real-time web search, backed by the Agent API `fast` preset. Great for quick questions and everyday searches.
  114. ### **perplexity_research**
  115. Deep, comprehensive research backed by the Agent API `high` preset. Ideal for thorough analysis and detailed reports. Runs can take minutes; the server streams the run and reports progress to clients that request it.
  116. ### **perplexity_reason**
  117. Advanced reasoning and problem-solving backed by the Agent API `medium` preset. Perfect for complex analytical tasks.
  118. `perplexity_ask` and `perplexity_reason` accept optional positive-integer `max_tokens` (total search context, up to 120,000) and `max_tokens_per_page` (context per result page, up to 20,000). These Agent API budgets control retrieved search content, not generated answer length. When omitted, the preset's search configuration remains in effect.
  119. The legacy `search_context_size` argument is still accepted, but is translated locally into explicit budgets rather than sent to the Agent API:
  120. | Legacy size | Total tokens | Tokens per page |
  121. |-------------|--------------|-----------------|
  122. | `low` | 2000 | 512 |
  123. | `medium` | 4000 | 1024 |
  124. | `high` | 8000 | 2048 |
  125. This compatibility policy is not an exact equivalent of Sonar's named sizes; the [Agent API migration guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/how-to) has no named-size equivalent. Each explicit budget overrides its corresponding legacy default.
  126. > [!NOTE]
  127. > Presets are managed configurations (model, search setup, step budget) that Perplexity keeps tuned over time; see the [presets guide](https://docs.perplexity.ai/docs/agent-api/presets). Earlier versions of this server called the legacy `sonar-pro`, `sonar-reasoning-pro`, and `sonar-deep-research` models and accepted `strip_thinking` / `reasoning_effort` parameters. Those parameters are no longer part of the tool schemas and are ignored if sent; the Agent API produces no `<think>` tags.
  128. ## Use as a Library
  129. The package also exports the server factory for embedding in your own Node process:
  130. ```ts
  131. import { createPerplexityServer } from "@perplexity-ai/mcp-server";
  132. // Single-tenant: reads PERPLEXITY_API_KEY from the environment.
  133. const server = createPerplexityServer("my-service");
  134. // Multi-tenant hosts resolve the key per call instead. When a provider is
  135. // set, the environment variable is never consulted, and a provider that
  136. // returns no key fails the call rather than falling back.
  137. const tenantServer = createPerplexityServer("my-service", {
  138. apiKey: () => currentRequestApiKey,
  139. });
  140. ```
  141. Mount the returned server on any MCP transport (stdio, streamable HTTP, in-memory).
  142. ## Troubleshooting
  143. - **API Key Issues**: Ensure `PERPLEXITY_API_KEY` is set correctly
  144. - **Connection Errors**: Check your internet connection and API key validity
  145. - **Tool Not Found**: Make sure the package is installed and the command path is correct
  146. - **Timeout Errors**: For very long research queries, set `PERPLEXITY_TIMEOUT_MS` to a higher value
  147. - **Proxy Issues**: Verify your `PERPLEXITY_PROXY` or `HTTPS_PROXY` setup and ensure `api.perplexity.ai` isn't blocked by your firewall.
  148. - **EOF / Initialize Errors**: Some strict MCP clients fail because `npx` writes installation messages to stdout. Use `npx -yq` instead of `npx -y` to suppress this output.
  149. For support, visit [community.perplexity.ai](https://community.perplexity.ai) or [file an issue](https://github.com/perplexityai/modelcontextprotocol/issues).
  150. ---

Ratings and comments

Sign in to rate this skill.

Sign in

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