Single-tool MCP server for Perplexity chat completions
npm install @zhangyu1818/server-perplexity-ask


Single-tool MCP server for Perplexity chat completions via a configurable API endpoint (default: OpenRouter).
perplexity/sonar model. Override the API endpoint with API_ENDPOINT and model with MODEL.1. Get your Perplexity API Key from the API Portal
2. Replace your_key_here in the configurations below with your API key
3. (Optional) Set API endpoint: API_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
4. (Optional) Set model: MODEL=perplexity/sonar
5. (Optional) Set timeout: PERPLEXITY_TIMEOUT_MS=600000 (default: 5 minutes)
6. (Optional) Set log level: PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR (default: ERROR)
``bash`
claude mcp add perplexity-ask --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @zhangyu1818/server-perplexity-ask
Or install via plugin:
`bash`
export PERPLEXITY_API_KEY="your_key_here"
claudeThen run: /plugin marketplace add perplexityai/modelcontextprotocol
Then run: /plugin install perplexity
We recommend using the one-click install badge at the top of this README for Cursor.
For manual setup, all these clients use the same mcpServers format:
| Client | Config File |
|--------|-------------|
| Cursor | ~/.cursor/mcp.json |claude_desktop_config.json
| Claude Desktop | |~/.codeium/windsurf/mcp_config.json
| Windsurf | |
`json`
{
"mcpServers": {
"perplexity-ask": {
"command": "npx",
"args": ["-y", "@zhangyu1818/server-perplexity-ask"],
"env": {
"PERPLEXITY_API_KEY": "your_key_here"
}
}
}
}
We 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:
`json`
{
"servers": {
"perplexity-ask": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@zhangyu1818/server-perplexity-ask"],
"env": {
"PERPLEXITY_API_KEY": "your_key_here"
}
}
}
}
`bash`
codex mcp add perplexity-ask --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @zhangyu1818/server-perplexity-ask
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.
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:
`bash`
export PERPLEXITY_PROXY=https://your-proxy-host:8080
If your proxy needs a username and password, use:
`bash`
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.https://
> URLs must include . Typical ports are 8080, 3128, and 80.
For cloud or shared deployments, run the server in HTTP mode.
#### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| PERPLEXITY_API_KEY | Your Perplexity API key | Required |API_ENDPOINT
| | Chat completions API endpoint | https://openrouter.ai/api/v1/chat/completions |MODEL
| | Model name to request | perplexity/sonar |PORT
| | HTTP server port | 8080 |BIND_ADDRESS
| | Network interface to bind to | 0.0.0.0 |ALLOWED_ORIGINS
| | CORS origins (comma-separated) | * |
#### Docker
`bash`
docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server
#### Node.js
`bash`
export PERPLEXITY_API_KEY=your_key_here
npm install && npm run build && npm run start:http
The server will be accessible at http://localhost:8080/mcp
- API Key Issues: Ensure PERPLEXITY_API_KEY is set correctlyPERPLEXITY_TIMEOUT_MS
- Connection Errors: Check your internet connection and API key validity
- Tool Not Found: Make sure the package is installed and the command path is correct
- Timeout Errors: For very long research queries, set to a higher valuePERPLEXITY_PROXY
- Proxy Issues: Verify your or HTTPS_PROXY setup and ensure your API endpoint isn't blocked by your firewall.npx
- EOF / Initialize Errors: Some strict MCP clients fail because writes installation messages to stdout. Use npx -yq instead of npx -y` to suppress this output.
For support, visit community.perplexity.ai or file an issue.
---