Installation

Install and configure the Perplexity MCP Server with your preferred AI assistant client

Get the Perplexity MCP Server up and running with your AI assistant in just a few minutes.

Prerequisites

Before you begin, ensure you have:

• Node.js 18 or higher installed on your system
• A Perplexity API key (we’ll get this in the next step)
• An MCP-compatible client installed (Cursor, Claude Desktop, VS Code, etc.)

Get Your API Key

1. Access the API Portal

   Navigate to the Perplexity API Portal and sign in to your account.

2. Generate API Key

   Create a new API key from the portal. Keep this key secure - you’ll need it for configuration.

3. Save Your Key

   Copy the API key to a secure location. You’ll use it in the next steps to configure your MCP client.

Never commit your API key to version control or share it publicly. Always use environment variables or secure configuration files.

Installation Methods

The Perplexity MCP Server can be installed using npm or run directly with npx (recommended):

npm install

npm install @perplexity-ai/mcp-server

Using npx -y is recommended as it always runs the latest version without requiring manual updates.

Environment Variables

The server supports several environment variables for configuration:

Variable	Description	Default	Required
PERPLEXITY_API_KEY	Your Perplexity API key	-	Yes
PERPLEXITY_TIMEOUT_MS	Request timeout in milliseconds	300000 (5 min)	No
PERPLEXITY_BASE_URL	Custom API base URL	https://api.perplexity.ai	No
PERPLEXITY_LOG_LEVEL	Logging level (DEBUG, INFO, WARN, ERROR)	ERROR	No
PERPLEXITY_PROXY	Proxy URL for corporate networks	-	No

Client Configuration

Choose your MCP client below for specific configuration instructions:

One-Click Installation

For the fastest setup, use the one-click install buttons:

• Cursor: Install in Cursor
• VS Code: Install in VS Code

Manual Configuration

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "perplexity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

Claude Code

Run this command in your terminal:

claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

Codex

Run this command in your terminal:

codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Replace your_key_here with your actual Perplexity API key in all configuration examples.

Verification

After installation, verify the server is working:

1. Restart Your Client

   Close and reopen your MCP client (Cursor, VS Code, etc.) to load the new configuration.

2. Check Available Tools

   Look for the Perplexity tools in your client’s tool list. You should see:

   • perplexity_search
   • perplexity_ask
   • perplexity_research
   • perplexity_reason
3. Test a Tool

   Try asking a simple question to verify the connection works. For example: “What’s the current weather in San Francisco?”

Troubleshooting

API Key Issues

Ensure PERPLEXITY_API_KEY is set correctly in your configuration file. The key should be from the Perplexity API Portal.

Connection Errors

Check your internet connection and verify your API key is valid. You can test the key directly via the Perplexity API.

Tool Not Found

Make sure the package path is correct in your configuration. Use npx -y @perplexity-ai/mcp-server for automatic version management.

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:

{
  "args": ["-yq", "@perplexity-ai/mcp-server"]
}

Timeout Errors

For very long research queries, increase the timeout:

{
  "env": {
    "PERPLEXITY_API_KEY": "your_key_here",
    "PERPLEXITY_TIMEOUT_MS": "600000"
  }
}

Proxy Configuration

If you’re behind a corporate firewall or proxy, configure the proxy settings:

{
  "env": {
    "PERPLEXITY_API_KEY": "your_key_here",
    "PERPLEXITY_PROXY": "https://your-proxy-host:8080"
  }
}

For authenticated proxies:

{
  "env": {
    "PERPLEXITY_API_KEY": "your_key_here",
    "PERPLEXITY_PROXY": "https://username:password@your-proxy-host:8080"
  }
}

The server checks proxy settings in this order: PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY. If none are set, it connects directly.

Next Steps

Quick Start Guide

Learn how to use the tools effectively

Tools Reference

Explore all available tools and their parameters