Perplexity MCP Server

repository·main·Indexed 25 days ago

https://github.com/perplexityai/modelcontextprotocol

An MCP server that provides AI assistants with real-time web search, reasoning, and deep research capabilities via the Perplexity API. It exposes four primary tools: perplexity_search for ranked results, perplexity_ask for general Q&A, perplexity_research for comprehensive investigations, and perplexity_reason for advanced problem-solving. Supports deployment via npx, Docker, or as a Node.js library with options for single-tenant and multi-tenant authentication.

Tokens: 4.2K
Snippets: 15
Records: 25
Agent score: 82%

What's inside @perplexity-ai/mcp-server

Install the Perplexity MCP Server
main
The Perplexity MCP Server provides AI assistants with real-time web search, reasoning, and research capabilities. You can install it in various environments using the following methods:
Claude Code
```
claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
```
Alternatively, via the plugin system:
```
export PERPLEXITY_API_KEY="your_key_here"
claude
# Then run:
# /plugin marketplace add perplexityai/modelcontextprotocol
# /plugin install perplexity
```
Codex
```
codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
```
IDEs (Cursor, Claude Desktop, Kiro, Windsurf, VS Code)
Most clients use an mcpServers configuration object. Add the following to your client's configuration file:
Client Config File
Cursor ~/.cursor/mcp.json
Claude Desktop claude_desktop_config.json
Kiro .kiro/settings/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
VS Code .vscode/mcp.json
```
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}
```
https://github.com/perplexityai/modelcontextprotocol/blob/main/README.md

Client	Config File
Cursor	`~/.cursor/mcp.json`
Claude Desktop	`claude_desktop_config.json`
Kiro	`.kiro/settings/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code	`.vscode/mcp.json`

Deploy Perplexity MCP Server as an HTTP Server

main

For cloud or shared deployments, you can run the server in HTTP mode. The server will be accessible at http://localhost:8080/mcp by default.

Docker Deployment

docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

Node.js Deployment

export PERPLEXITY_API_KEY=your_key_here
npm install && npm run build && npm run start:http

HTTP Server Configuration Variables

Variable	Description	Default
`PORT`	HTTP server port	`8080`
`BIND_ADDRESS`	Network interface to bind to (e.g., `0.0.0.0`)	`127.0.0.1`
`ALLOWED_ORIGINS`	CORS origins (comma-separated)	(empty)
`ALLOWED_HOSTS`	Additional `Host` header values to accept	(loopback only)

docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

Run the Perplexity MCP Server in HTTP mode
main
By default, the Docker container runs in HTTP mode. You must provide your Perplexity API key via the PERPLEXITY_API_KEY environment variable. The server will be accessible at http://localhost:8080/mcp.
```
docker run --rm -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server
```
https://github.com/perplexityai/modelcontextprotocol/blob/main/DOCKER.md
Build the Perplexity MCP Server Docker image
main
To build the Docker image, run the build command from the project root. This creates an image tagged as perplexity-mcp-server.
```
docker build -t perplexity-mcp-server .
```
https://github.com/perplexityai/modelcontextprotocol/blob/main/DOCKER.md
Run the Perplexity MCP Server in STDIO mode for local development
main
For local development using STDIO transport instead of HTTP, run the server directly using npm. Note that the Docker image is optimized for HTTP mode; for STDIO, use the local npm/npx method.
```
npm install
npm run build
PERPLEXITY_API_KEY=your_key_here npm start
```
https://github.com/perplexityai/modelcontextprotocol/blob/main/DOCKER.md
Integrate the HTTP Docker server with MCP clients
main
When using the Dockerized HTTP server, configure your MCP client (e.g., Claude Desktop) to connect to the specific MCP endpoint URL.
```
{
  "mcpServers": {
    "perplexity": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```
https://github.com/perplexityai/modelcontextprotocol/blob/main/DOCKER.md
Run the Perplexity MCP Server using an environment file
main
To avoid long CLI commands, create a .env file with your configuration and use the --env-file flag.
```
# .env file content
PERPLEXITY_API_KEY=your_key_here
PERPLEXITY_TIMEOUT_MS=600000
PERPLEXITY_PROXY=https://your-proxy-host:8080
PORT=8080

# Run command
docker run --rm -p 8080:8080 --env-file .env perplexity-mcp-server
```
https://github.com/perplexityai/modelcontextprotocol/blob/main/DOCKER.md

Configure Perplexity MCP Server Environment Variables

main

The server can be customized using several environment variables:

Variable	Description	Default
`PERPLEXITY_API_KEY`	Your Perplexity API key	Required
`PERPLEXITY_TIMEOUT_MS`	Timeout in milliseconds (useful for long research tasks)	300000 (5 mins)
`PERPLEXITY_BASE_URL`	Custom base URL for API requests	`https://api.perplexity.ai`
`PERPLEXITY_LOG_LEVEL`	Log level (`DEBUG`, `INFO`, `WARN`, `ERROR`)	`ERROR`
`PERPLEXITY_PROXY`	HTTPS proxy address (e.g., `https://proxy:8080`)	N/A

Configure the PERPLEXITY_API_KEY environment variable
main
To run the Perplexity MCP server, you must provide a valid Perplexity API key via the PERPLEXITY_API_KEY environment variable. If this variable is missing, the server will fail to start and exit with an error.
https://github.com/perplexityai/modelcontextprotocol/blob/main/src/index.ts
Troubleshoot Perplexity MCP Server
main
Common issues and solutions:
- API Key Issues: Verify PERPLEXITY_API_KEY is correctly set.
- Timeout Errors: For long research tasks, increase PERPLEXITY_TIMEOUT_MS.
- Proxy Issues: Ensure PERPLEXITY_PROXY or HTTPS_PROXY is set correctly and api.perplexity.ai is accessible.
- 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.
- Tool Not Found: Verify the package is installed and the command path is correct.
https://github.com/perplexityai/modelcontextprotocol/blob/main/README.md
Use Perplexity MCP Server as a Library
main
You can embed the Perplexity MCP server into your own Node.js application using the createPerplexityServer factory. This allows for both single-tenant and multi-tenant implementations.
- Single-tenant: The server automatically reads PERPLEXITY_API_KEY from the environment.
- Multi-tenant: You can provide an apiKey function that resolves the key per request. If a provider returns no key, the call fails.
Mount the returned server on any MCP transport (stdio, streamable HTTP, or in-memory).
```
import { createPerplexityServer } from "@perplexity-ai/mcp-server";

// Single-tenant: reads PERPLEXITY_API_KEY from the environment.
const server = createPerplexityServer("my-service");

// Multi-tenant hosts resolve the key per call instead.
const tenantServer = createPerplexityServer("my-service", {
  apiKey: () => currentRequestApiKey,
});
```
https://github.com/perplexityai/modelcontextprotocol/blob/main/README.md

Configure Perplexity API via Environment Variables

main

The server uses several environment variables for configuration:

Variable	Description
`PERPLEXITY_API_KEY`	Required. Your Perplexity API key.
`PERPLEXITY_BASE_URL`	The base URL for the API. Defaults to `https://api.perplexity.ai`.
`PERPLEXITY_PROXY`	URL for a proxy server. If set, `proxyAwareFetch` uses `undici.ProxyAgent`.
`HTTPS_PROXY` / `HTTP_PROXY`	Fallback proxy environment variables.
`PERPLEXITY_TIMEOUT_MS`	Request timeout in milliseconds. Defaults to `300000` (5 minutes).

Perplexity MCP Server

What's inside @perplexity-ai/mcp-server

Claude Code

Codex

IDEs (Cursor, Claude Desktop, Kiro, Windsurf, VS Code)

Docker Deployment

Node.js Deployment

HTTP Server Configuration Variables