Perplexity MCP server for AI agents

The Perplexity MCP Server provides access to Perplexity AI's powerful search capabilities through the Model Context Protocol. It enables web search, academic research, financial data retrieval, and advanced filtering options, automatically returning source URLs for additional information retrieval.

Installation

Prerequisites

Go 1.23 or later
A Perplexity API key

Setup

Clone the repository
Build and run the server:

./run.sh

Configuration

Required Environment Variables

PERPLEXITY_API_KEY: Your Perplexity AI API key

Optional Environment Variables

PERPLEXITY_DEFAULT_MODEL: Default model to use (default: "sonar")
- sonar: Fast, cost-effective search for quick facts
- sonar-pro: Comprehensive search with better depth and coverage
PERPLEXITY_MAX_TOKENS: Maximum tokens in response (default: 1024)
PERPLEXITY_TEMPERATURE: Response randomness 0-2 (default: 0.2)
PERPLEXITY_TOP_P: Nucleus sampling parameter (default: 0.9)
PERPLEXITY_TOP_K: Top-k sampling parameter (default: 0)
PERPLEXITY_TIMEOUT: Request timeout duration (default: 30s)
PERPLEXITY_RETURN_IMAGES: Include images by default (default: false)
PERPLEXITY_RETURN_RELATED: Include related questions by default (default: false)

Usage

Running the Server

MCP Server Mode (Default)

export PERPLEXITY_API_KEY="your-api-key"
./perplexity

Test Mode

export PERPLEXITY_API_KEY="your-api-key"
./perplexity -test

MCP Client Configuration

To use this server with an MCP client, add it to your client configuration:

{
  "servers": {
    "perplexity": {
      "command": "path/to/perplexity",
      "env": {
        "PERPLEXITY_API_KEY": "your-api-key"
      }
    }
  }
}

Available Search Functions

perplexity_search

Perform a general web search with real-time information.

Parameters:

query (required): The search query
model: Choose 'sonar' for quick searches or 'sonar-pro' for comprehensive results
search_domain_filter: Array of domains to include
search_exclude_domains: Array of domains to exclude
search_recency_filter: Time filter (hour, day, week, month, year)
return_images: Include images
return_related_questions: Include related questions
max_tokens: Maximum response tokens
temperature: Response randomness (0-2)
date_range_start: Start date (YYYY-MM-DD)
date_range_end: End date (YYYY-MM-DD)
location: Geo-specific search location

Example:

{
  "query": "latest AI developments",
  "model": "sonar-pro",
  "search_recency_filter": "week",
  "return_citations": true
}

perplexity_academic_search

Search academic papers and scholarly content.

Parameters:

query (required): The academic search query
subject_area: Academic subject (e.g., "Physics", "Computer Science")
model: Defaults to 'sonar-pro' for comprehensive academic results
search_domain_filter: Array of academic domains
search_recency_filter: Time filter
max_tokens: Maximum response tokens
temperature: Response randomness

Example:

{
  "query": "quantum computing applications",
  "subject_area": "Physics",
  "search_recency_filter": "year"
}

perplexity_financial_search

Search financial data and SEC filings.

Parameters:

query (required): The financial search query
ticker: Stock ticker symbol (e.g., "AAPL")
company_name: Company name
report_type: Financial report type (e.g., "10-K", "10-Q", "8-K")
model: Defaults to 'sonar-pro' for comprehensive financial data
search_recency_filter: Time filter
date_range_start: Report start date
date_range_end: Report end date
max_tokens: Maximum response tokens

Example:

{
  "query": "quarterly earnings",
  "ticker": "MSFT",
  "report_type": "10-Q",
  "search_recency_filter": "month"
}

perplexity_filtered_search

Advanced search with comprehensive filtering.

Parameters:

query (required): The search query
model: Choose based on needs (defaults to sonar-pro)
search_domain_filter: Array of domains to include
search_exclude_domains: Array of domains to exclude
search_recency_filter: Time filter
content_type: Type of content (news, academic, blog, etc.)
file_type: File type filter (pdf, doc, html, etc.)
language: Language filter
country: Country for geo-specific search
date_range_start: Start date
date_range_end: End date
return_citations: Include citations
return_images: Include images
return_related_questions: Include related questions
max_tokens: Maximum response tokens
temperature: Response randomness
custom_filters: Object with additional key-value filters

Example:

{
  "query": "renewable energy innovations",
  "content_type": "news",
  "language": "English",
  "country": "Germany",
  "search_recency_filter": "month",
  "custom_filters": {
    "industry": "energy",
    "technology": "solar"
  }
}

Response Format

All search functions return responses in this format:

Main Content: Search results and answer
Source URLs: List of source URLs for additional information
Detailed Sources (if available): Title, URL, and snippet for each source
Related Questions (if requested): Suggested follow-up questions

Example response structure:

[Main search results content...]

## Source URLs
1. https://example.com/article1
2. https://example.com/article2
3. https://example.com/article3

## Detailed Sources
1. **Article Title**
   URL: https://example.com/article1
   Snippet: Brief excerpt from the article...

## Related Questions
- What are the latest developments?
- How does this compare to...?

Error Handling

The server handles various error conditions:

Invalid or missing API key (401)
Rate limiting (429)
Invalid parameters (400)
Server errors (500)

Errors are returned with descriptive messages to help diagnose issues.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "perplexity" '{"command":"/path/to/binary/perplexity-server","env":{"PERPLEXITY_API_KEY":"your-perplexity-key"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "perplexity": {
            "command": "/path/to/binary/perplexity-server",
            "env": {
                "PERPLEXITY_API_KEY": "your-perplexity-key"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "perplexity": {
            "command": "/path/to/binary/perplexity-server",
            "env": {
                "PERPLEXITY_API_KEY": "your-perplexity-key"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect