Perplexity MCP Server

An MCP server that provides Perplexity AI web search capabilities to Claude, with automatic model selection, stateful filters, and 10 purpose-built tools.

<a href="https://glama.ai/mcp/servers/6qmvjay9z5">

</a>

Prerequisites

- Node.js v20 or higher
- A Perplexity API key — get one at <https://www.perplexity.ai/settings/api>
- Claude Desktop (or any MCP-compatible client)

Installation

1. Clone this repository:

    git clone https://github.com/RossH121/perplexity-mcp.git
    cd perplexity-mcp
    

2. Install dependencies:

    npm install
    

3. Build the server:

    npm run build
    

Configuration

Add the server to Claude's config file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "perplexity-server": {
      "command": "node",
      "args": ["/absolute/path/to/perplexity-mcp/build/index.js"],
      "env": {
        "PERPLEXITY_API_KEY": "your-api-key-here",
        "PERPLEXITY_MODEL": "sonar-pro"
      }
    }
  }
}

Replace /absolute/path/to with the actual path to where you cloned the repository.

Available Models

The server automatically selects the best model based on your query, but you can also set a default via PERPLEXITY_MODEL:

| Model | Best for |
|---|---|
| sonar-deep-research | Comprehensive reports, exhaustive multi-source research |
| sonar-reasoning-pro | Complex logic, math, chain-of-thought analysis |
| sonar-pro | General search, factual queries (default) |
| sonar | Quick, simple lookups |

For pricing and availability: <https://docs.perplexity.ai/guides/pricing>

Tools

search — AI-powered web search

The main search tool. Automatically selects the right model based on your query. Returns a synthesized answer with cited sources.

| Parameter | Options | Description |
|---|---|---|
| query | string | Your search query |
| search_context_size | low / medium / high | How much web context to retrieve. low is fastest/cheapest (default), high is most thorough |
| search_type | fast / pro / auto | Search engine tier (nested in web_search_options) |
| reasoning_effort | minimal / low / medium / high | Depth of reasoning for sonar-deep-research |
| strip_thinking | boolean | Remove <think>...</think> blocks from reasoning model responses |
| search_mode | web / academic / sec | academic prioritizes peer-reviewed papers; sec searches SEC filings |
| search_after_date / search_before_date | MM/DD/YYYY | Filter sources by publication date |
| last_updated_after / last_updated_before | MM/DD/YYYY | Filter sources by last-updated date |
| search_language_filter | ["en","de"] | Restrict sources to languages (ISO 639-1) |
| language_preference | ISO 639-1 | Preferred response language |
| disable_search | boolean | Answer from training data only (no web search) |
| enable_search_classifier | boolean | Let a classifier decide whether to search |
| return_images | boolean | Append an Images section of result URLs |
| image_domain_filter / image_format_filter | string[] | Restrict images by domain or format |
| return_related_questions | boolean | Append follow-up question suggestions |
| country / latitude / longitude | — | Localize results via user_location |
| stream_mode | full / concise | Streaming event format for Pro Search |
| show_cost | boolean | Append a request-cost footer when available |
| stream | boolean | Enable streaming responses |

Examples:
- "What's the latest on fusion energy?" → auto-selects sonar-pro
- "Deep research analysis of CRISPR gene editing advances" → auto-selects sonar-deep-research
- "Solve this logic puzzle step by step" → auto-selects sonar-reasoning-pro

raw_search — Raw ranked results (no LLM)

Returns ranked web results directly without AI synthesis. Faster and cheaper — useful for URL discovery, building source lists, or fact-checking pipelines.

| Parameter | Options | Description |
|---|---|---|
| query | string or string[] | Search query, or an array of queries run in one request |
| max_results | 1–20 | Number of results (default: 10) |
| max_tokens / max_tokens_per_page | number | Token budget overall / per result |
| search_mode | web / academic / sec | Source category |
| search_type | web / people | people routes to People Search |
| recency | hour / day / week / month / year | Time window filter |
| search_after_date / search_before_date | MM/DD/YYYY | Filter by publication date |
| last_updated_after / last_updated_before | MM/DD/YYYY | Filter by last-updated date |
| search_language_filter | ["en","de"] | Restrict to languages (ISO 639-1) |
| country | ISO 3166 code | Localize results (e.g. US, GB) |

> Note: prior versions sent these params in camelCase, which the Search API silently ignored — so max_results, recency, search_mode and the date filters had no effect. This is fixed; they now take effect.

async_research — Long-running deep research

Submit a sonar-deep-research job and poll it, instead of blocking on a synchronous call. Useful when research may exceed the 5-minute synchronous timeout. Jobs expire 7 days after creation.

| Parameter | Options | Description |
|---|---|---|
| action | submit / status / list | What to do |
| query | string | Research question (required for submit) |
| request_id | string | Job id from a prior submit (required for status) |
| model | Sonar model | Job model (default: sonar-deep-research) |
| reasoning_effort | minimal / low / medium / high | Reasoning depth |
| search_mode | web / academic / sec | Source category |
| strip_thinking | boolean | Strip <think> blocks from the completed result |

"Submit async research: comprehensive comparison of solid-state battery startups"
→ returns a request_id
"Check async research status for <request_id>"

agent — Agentic loop with built-in tools

The Perplexity Agent API. Runs a multi-step agent that can call built-in tools and optionally a third-party model.

| Parameter | Options | Description |
|---|---|---|
| input | string | The task or question |
| model | e.g. openai/gpt-4.1 | Provider-qualified model |
| models | string[] | Fallback chain (takes precedence over model) |
| preset | fast-search / pro-search / deep-research | Named preset instead of a model |
| instructions | string | System prompt |
| max_steps | 1–10 | Max agentic/tool steps |
| max_output_tokens | number | Max output tokens |
| tools | web_search / fetch_url | Built-in tools the agent may use |

embeddings — Text embeddings

Generate embeddings via the Perplexity Embeddings API. Returns a compact summary (model, vector count, token usage) by default.

| Parameter | Options | Description |
|---|---|---|
| input | string or string[] | Text(s) to embed (max 512) |
| model | pplx-embed-v1-0.6b / pplx-embed-v1-4b | Embedding model (default: 0.6b) |
| dimensions | number | Output dimensions (Matryoshka) |
| full | boolean | Include raw base64-encoded vectors |

domain_filter — Allowlist/blocklist domains

Restrict or exclude specific domains from search results. Filters persist across all subsequent searches until cleared.

- action: "allow" — restrict results to this domain (allowlist mode)
- action: "block" — exclude this domain from results (denylist mode)
- Maximum 20 domains; cannot mix allow and block in the same filter set

"Allow results only from arxiv.org and nature.com"
"Block pinterest.com and reddit.com from search results"

recency_filter — Time window filter

Limit search results to a specific time period. Persists until changed.

Options: hour, day, week, month, year, none

"Set recency filter to week"
"Remove the recency filter"

clear_filters — Reset all filters

Clears all domain and recency filters in one call.

list_filters — View active filters

Shows currently active domain allowlist/blocklist and recency setting.

model_info — View or override model selection

View available models and current selection, or manually force a specific model.

"Show model info"
"Set model to sonar-deep-research"

Intelligent Model Selection

The server scores your query against keyword lists to automatically pick the right model:

- Research keywords (deep research, comprehensive, in-depth) → sonar-deep-research
- Reasoning keywords (solve, logic, mathematical, figure out) → sonar-reasoning-pro
- Simple keywords (quick, brief, basic) → sonar
- Everything else → sonar-pro

Each response shows which model was used and why. If a query strongly matches a model (score ≥ 2), it will override a manually set model.

Example Workflows

Time-sensitive research with domain filtering:
1. recency_filter → week
2. domain_filter → allow nature.com, allow arxiv.org
3. search → "Recent breakthroughs in quantum error correction"

Financial document research:
1. raw_search with search_mode: "sec" → find relevant filings
2. search with search_mode: "sec" → synthesized analysis

Academic literature review:
1. search with search_mode: "academic", search_context_size: "high" → comprehensive results from peer-reviewed sources

Deep research with reasoning control:
1. search with reasoning_effort: "high", strip_thinking: true → thorough analysis without <think> blocks in the output

Development

npm run build   # Compile TypeScript to build/
npm start       # Run the built server

Source is in src/ — after editing, rebuild and restart Claude to load changes.

License

MIT