Perplexity Ask

What is Perplexity Ask about?

Enables Claude and other MCP‑compatible AI agents to perform live, web‑wide research by calling the Perplexity Sonar API. The server exposes a perplexity_ask tool that accepts a standard message array and returns search‑augmented responses.

How to use Perplexity Ask?

1. Clone the repository

   git clone git@github.com:ppl-ai/modelcontextprotocol.git
   cd modelcontextprotocol/perplexity-ask && npm install
   

2. Obtain a Sonar (Perplexity) API key from the Perplexity developer portal and set it as PERPLEXITY_API_KEY in your environment.
3. Run the server – the recommended approach is via npx:

   {
     "mcpServers": {
       "perplexity-ask": {
         "command": "npx",
         "args": ["-y", "server-perplexity-ask"],
         "env": { "PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE" }
       }
     }
   }
   

   Alternatively, you can build and run the Docker image:

   docker build -t mcp/perplexity-ask:latest -f Dockerfile .
   docker run -i --rm -e PERPLEXITY_API_KEY=$PERPLEXITY_API_KEY mcp/perplexity-ask
   

4. Configure Claude Desktop or any MCP‑compatible client by adding the above configuration to claude_desktop_config.json or the corresponding MCP settings.

Key Features of Perplexity Ask

• Live web search through the Perplexity Sonar API.
• Exposes a single tool perplexity_ask that follows the MCP message format.
• Dockerized image for isolated deployment.
• npx based launch for quick, zero‑setup execution.
• Easy parameter tweaking in index.ts for custom search behavior.
• Built‑in troubleshooting guidance and MIT licensing.

Use Cases of Perplexity Ask

• Augmenting Claude (or other LLMs) with up‑to‑date internet information.
• Building research assistants that can cite current sources.
• Enabling developers to add web‑search capabilities to custom MCP servers.
• Integrating live search into IDE extensions such as Cursor.

FAQ for Perplexity Ask

Q: Where do I get the API key? A: Sign up at the Perplexity Sonar API page, generate a key in the developer dashboard, and set it as PERPLEXITY_API_KEY.

Q: Can I customize the search parameters? A: Yes. Edit the API call in index.ts to modify temperature, top‑p, or other Perplexity options.

Q: Which command is preferred for running the server? A: The npx command (npx -y server-perplexity-ask) is the most convenient, but Docker is also supported.

Q: What models can use this server? A: Any MCP‑compatible model (e.g., Claude Desktop) that can call MCP tools.

Q: How do I debug issues? A: Consult the troubleshooting guide linked in the README or contact api@perplexity.ai.

Perplexity Ask MCP Server

An MCP server implementation that integrates the Sonar API to provide Claude with unparalleled real-time, web-wide research.

Please refer to the official DeepWiki page for assistance with implementation.

High-level System Architecture

Credits: DeepWiki powered by Devin

Tools

• perplexity_ask
  • Engage in a conversation with the Sonar API for live web searches.
  • Inputs:
    • messages (array): An array of conversation messages.
      • Each message must include:
        • role (string): The role of the message (e.g., system, user, assistant).
        • content (string): The content of the message.

Configuration

Step 1:

Clone this repository:

git clone git@github.com:ppl-ai/modelcontextprotocol.git

Navigate to the perplexity-ask directory and install the necessary dependencies:

cd modelcontextprotocol/perplexity-ask && npm install

Step 2: Get a Sonar API Key

1. Sign up for a Sonar API account.
2. Follow the account setup instructions and generate your API key from the developer dashboard.
3. Set the API key in your environment as PERPLEXITY_API_KEY.

Step 3: Configure Claude Desktop

1. Download Claude desktop here.

2. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "perplexity-ask": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PERPLEXITY_API_KEY",
        "mcp/perplexity-ask"
      ],
      "env": {
        "PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "perplexity-ask": {
      "command": "npx",
      "args": [
        "-y",
        "server-perplexity-ask"
      ],
      "env": {
        "PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

You can access the file using:

vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 4: Build the Docker Image

Docker build:

docker build -t mcp/perplexity-ask:latest -f Dockerfile .

Step 5: Testing

Let's make sure Claude for Desktop is picking up the two tools we've exposed in our perplexity-ask server. You can do this by looking for the hammer icon:

After clicking on the hammer icon, you should see the tools that come with the Filesystem MCP Server:

If you see both of these this means that the integration is active. Congratulations! This means Claude can now ask Perplexity. You can then simply use it as you would use the Perplexity web app.

Step 6: Advanced parameters

Currently, the search parameters used are the default ones. You can modify any search parameter in the API call directly in the index.ts script. For this, please refer to the official API documentation.

Troubleshooting

The Claude documentation provides an excellent troubleshooting guide you can refer to. However, you can still reach out to us at api@perplexity.ai for any additional support or file a bug.

Cursor integration

You can also use our MCP with Cursor (or any other app that supports this). To use Sonar with Cursor, you can follow the following steps.

Step 1: Navigate to your Cursor settings:

Step 2: Navigate to the MCP directory

And click on Add new global MCP server

Step 3: Insert the MCP Server Configuration from above

This is the same configuration you would use for any other application that supports MCP.

You should then see the application being part of your available tools like this:

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.