MCP Client Configuration

Configure the Perplexity MCP Server with various MCP clients including Claude Code, Cursor, VS Code, and more

Overview

The Perplexity MCP Server works with multiple MCP clients. This guide shows you how to configure each supported client.

Before configuring any client, make sure you have your Perplexity API key ready.

Quick Install Options

One-Click Installation

Several clients support one-click installation:

Cursor

Install directly in Cursor

VS Code

Install directly in VS Code

Client-Specific Configuration

Claude Code

Command Line Installation

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

Plugin Installation

export PERPLEXITY_API_KEY="your_key_here"
claude
# Then run: /plugin marketplace add perplexityai/modelcontextprotocol
# Then run: /plugin install perplexity

The plugin installation method requires setting the API key as an environment variable before launching Claude.

Cursor

One-Click Install (Recommended)

Use the install badge at the top of the README for the easiest setup.

Manual Configuration

Edit ~/.cursor/mcp.json:

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

If you encounter EOF or Initialize errors, replace "-y" with "-yq" in the args array to suppress npx output.

Claude Desktop

Configuration File

Edit claude_desktop_config.json:

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

The location of claude_desktop_config.json varies by platform. Check the Claude Desktop documentation for your operating system.

Windsurf

Configuration File

Edit ~/.codeium/windsurf/mcp_config.json:

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

VS Code

One-Click Install (Recommended)

Use the install badge at the top of the README for the easiest setup.

Manual Configuration

Create or edit .vscode/mcp.json in your workspace:

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

VS Code uses a different configuration format with a servers wrapper and type field.

Codex

Command Line Installation

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

Configuration Formats

Different clients use different configuration formats:

mcpServers Format (Cursor, Claude Desktop, Windsurf)

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

Additional Environment Variables

You can add any environment variable to the env object in your configuration:

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

Troubleshooting

EOF / Initialize Errors

Some strict MCP clients fail because npx writes installation messages to stdout.

Solution: Use npx -yq instead of npx -y to suppress output:

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

Tool Not Found

Check:

1. Ensure the package is installed correctly
2. Verify the command path is correct
3. Try running npx @perplexity-ai/mcp-server manually to test

API Key Issues

Check:

1. Ensure PERPLEXITY_API_KEY is set correctly in the env object
2. Verify your API key is valid at the API Portal
3. Make sure there are no extra spaces or quotes in the key

Connection Errors

Check:

1. Your internet connection
2. Your API key validity
3. If behind a corporate firewall, see Proxy Setup

Other MCP Clients

Most MCP clients can be manually configured using the mcpServers wrapper format (like Cursor, Claude Desktop, and Windsurf). If your client doesn’t work with this format, check its documentation for the correct configuration wrapper.