DOCSEARCHbyAlgolia
Submit Docs

Perplexity MCP Server

repository·main·Indexed 43 days ago

https://github.com/dainfernalcoder/perplexity-mcp

An MCP server providing intelligent search, reasoning, and research capabilities powered by Perplexity AI models. It features automatic query complexity detection to route tasks between Sonar Pro (search), Sonar Reasoning Pro (reason), and Sonar Deep Research (deep_research) tools. Version 0.2.3.

Tokens
3.6K
Snippets
10
Records
17
Agent score
47%

What's inside Perplexity MCP

  1. When to use deep_research vs search

    main

    Choosing between the search and deep_research tools depends on the required depth of information:

    Featuresearch tooldeep_research tool
    Primary UseQuick answers and general infoComprehensive, in-depth analysis
    DepthSurface-level/StandardHigh depth and breadth
    ComplexitySimple queriesComplex, nuanced topics
    PerspectivesSingle/DirectMultiple perspectives and viewpoints
    FocusBroadAbility to target specific focus_areas
    CitationsStandardThorough citation of sources and expert opinions

  2. Understand the available Perplexity AI models

    main

    The server provides access to three distinct Perplexity models, each suited for different task complexities:

    1. Sonar Pro: Best for quick information retrieval, simple query processing, and direct answers.
    2. Sonar Reasoning Pro: Best for complex analysis, multi-step reasoning, and detailed explanations.
    3. Sonar Deep Research: Best for comprehensive research, in-depth analysis, and generating structured reports.

  3. How the Perplexity MCP Server routes queries

    main

    The Perplexity MCP Server uses intelligent query analysis to automatically route requests to one of three specialized tools based on the detected complexity of the query. This ensures that simple questions get fast, concise answers while complex research tasks get the depth they require.

    Routing Logic

    • search (Sonar Pro): Used for quick information lookup, simple factual queries, and direct, concise answers.
    • reason (Sonar Reasoning Pro): Used for complex problem-solving, multi-step analysis, comparisons, trade-offs, and detailed 'how/why' explanations.
    • deep_research (Sonar Deep Research): Used for comprehensive research, in-depth analysis, exploring multiple perspectives, and generating reports with source references.

    While the server performs automatic pattern-based complexity detection, users can manually control which model is used via the force_model flag.

  4. Set up the Perplexity MCP Server locally

    main

    Follow these steps to install and prepare the server for local use:

    1. Clone the repository to your local machine.
    2. Install dependencies using your preferred package manager (e.g., npm install).
    3. Build the TypeScript source to generate the executable JavaScript files.
    4. Configure your API key by setting the PERPLEXITY_API_KEY environment variable.

  5. Install and configure the Perplexity MCP Server

    main

    To set up the Perplexity MCP server, ensure you have Node.js installed and a valid Perplexity API key. You can configure the server in your MCP settings file using one of the following methods:

    Method 1: Local Installation

    Point the command to node and provide the absolute path to the build file in args.

    Method 2: NPX (Recommended for macOS)

    Use npx to run the server without a local installation.

    Method 3: Fallback for Environment Variable Issues

    If your MCP client cannot parse environment variables (e.g., "${env:PERPLEXITY_API_KEY}"), use one of these fallbacks:

    1. Command-Line Argument: Pass the key directly using --api-key.
    2. Explicit .env File: Use the --cwd flag to point to a directory containing a .env file with your PERPLEXITY_API_KEY.
    // Recommended NPX configuration
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": [
        "-y",
        "perplexity-mcp"
      ],
      "env": {
        "PERPLEXITY_API_KEY": "your_api_key"
      }
    }
  }
}

  7. How query complexity affects tool selection

    main

    The Perplexity MCP server features an intelligent routing mechanism. If a user calls the search tool without setting force_model: true, the server analyzes the query to determine if a more powerful model is required:

    • Research Indicators: If the query contains words like analyze, research, investigate, or comprehensive, the server automatically upgrades the request to the deep_research tool (sonar-deep-research).
    • Complex Indicators: If the query contains words like how, why, explain, or difference between, the server upgrades the request to the reason tool (sonar-reasoning-pro).
    • Simple Queries: If no indicators are found, it proceeds with the search tool (sonar-pro).

    To bypass this automatic routing and use a specific model, set force_model: true in your tool arguments.

  8. Configure the Perplexity API Key

    main

    The Perplexity MCP server requires an API key to function. You can provide the key using one of the following three methods, listed in order of priority:

    1. Environment Variable (Recommended): Set the PERPLEXITY_API_KEY environment variable. This is the most secure method for production.
    2. Command-line Argument: Pass the key directly using the --api-key flag.
    3. .env File: Create a .env file containing PERPLEXITY_API_KEY=your-api-key in a specific directory and point the server to that directory using the --cwd flag.

    Note: Automatic .env file discovery is disabled. You must explicitly use --cwd if you want the server to read from a .env file.

    # Method 1: Environment Variable
export PERPLEXITY_API_KEY="your-key-here" && npx perplexity-mcp

# Method 2: Command-line Argument
npx perplexity-mcp --api-key "your-key-here"

# Method 3: .env file with --cwd
npx perplexity-mcp --cwd /path/to/project

  9. Use the deep_research tool for in-depth analysis

    main

    The deep_research tool utilizes Perplexity's sonar-deep-research model to conduct comprehensive investigations into complex topics. It is designed for scenarios requiring thorough analysis, multiple perspectives, and detailed information that exceeds the capabilities of a standard search tool.

    Parameters

    • query (required): The research query or topic to investigate in depth.
    • focus_areas (optional): An array of strings specifying particular aspects to prioritize during the research process.
    • output_format (optional): The format of the response. Supported values are text or dropdown. Defaults to text.
    const result = await use_mcp_tool({
  server_name: "perplexity-ask",
  tool_name: "deep_research",
  arguments: {
    query: "The impact of quantum computing on cryptography",
    focus_areas: [
      "Post-quantum cryptographic algorithms",
      "Timeline for quantum threats to current encryption",
      "Practical mitigation strategies for organizations"
    ]
  }
});

console.log(result);

  10. Use the Deep Research tool (Sonar Deep Research)

    main

    The deep_research tool conducts comprehensive research to generate detailed reports. It is ideal for in-depth analysis of complex topics. It accepts a focus_areas array to guide the research toward specific sub-topics.

    const result = await use_mcp_tool({
  server_name: "perplexity",
  tool_name: "deep_research",
  arguments: {
    query: "The impact of quantum computing on cryptography",
    focus_areas: [
      "Post-quantum cryptographic algorithms",
      "Timeline for quantum threats",
      "Practical mitigation strategies"
    ],
    force_model: false // Optional: force using this model even if query seems simple
  }
});

  11. Use the Reason tool (Sonar Reasoning Pro)

    main

    The reason tool handles complex, multi-step tasks that require detailed analysis, such as explanations, comparisons, and problem-solving. Use the force_model argument to force the use of the Sonar Reasoning Pro model even if the query appears simple.

    const result = await use_mcp_tool({
  server_name: "perplexity",
  tool_name: "reason",
  arguments: {
    query: "Compare and contrast REST and GraphQL APIs, explaining their pros and cons",
    force_model: false // Optional: force using this model even if query seems simple
  }
});

  12. Use the Search tool (Sonar Pro)

    main

    The search tool is designed for quick searches and basic information lookup. It is best suited for straightforward questions that require concise, direct answers. You can optionally use the force_model argument to bypass automatic query complexity detection and force the use of the Sonar Pro model.

    const result = await use_mcp_tool({
  server_name: "perplexity",
  tool_name: "search",
  arguments: {
    query: "What is the capital of France?",
    force_model: false // Optional: force using this model even if query seems complex
  }
});