Skip to main content
Glama
RossH121

Perplexity MCP Server

by RossH121

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.

Prerequisites

Related MCP server: Perplexity MCP Server

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

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

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_filterweek

  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

Available Tools

6 tools
clear_filtersA

Remove all domain filters (both allowed and blocked). Use when switching search contexts or starting fresh. Does not affect recency filter.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It effectively discloses key behavioral traits: it's a destructive operation (removes filters), specifies what gets affected (domain filters) and what doesn't (recency filter), and implies a reset context. However, it doesn't mention permissions, side effects, or response format, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and well-structured in two sentences: the first states the purpose and scope, the second provides usage guidelines and exclusions. Every sentence adds clear value with zero waste, making it easy to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is nearly complete. It covers purpose, usage, and behavioral aspects effectively. However, it lacks details on permissions or confirmation prompts, which could be relevant for a destructive operation, leaving minor room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the lack of inputs. The description adds no parameter-specific information, which is appropriate here. A baseline of 4 is applied as it compensates adequately for the zero-parameter case by focusing on usage context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Remove all domain filters') and specifies the scope ('both allowed and blocked'), distinguishing it from sibling tools like 'domain_filter' which likely manages individual filters. It goes beyond just restating the name by detailing what exactly gets cleared.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides usage scenarios ('when switching search contexts or starting fresh') and clarifies exclusions ('Does not affect recency filter'), offering clear guidance on when to use this tool versus alternatives like 'recency_filter' or 'list_filters'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

domain_filterA

Configure domain filtering for search results. Use 'allow' to prioritize trusted sources (e.g., documentation sites, academic domains) or 'block' to exclude unreliable sources. Maximum 20 domains total. Filters persist across searches until cleared.

ParametersJSON Schema
NameRequiredDescriptionDefault
domainYesDomain name without protocol. Examples: 'wikipedia.org', 'docs.python.org', 'arxiv.org'. For subdomains: 'api.example.com'
actionYes'allow' prioritizes this domain in results, 'block' excludes it completely

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it specifies the maximum limit of 20 domains, persistence across searches until cleared, and the effect of actions ('allow' prioritizes, 'block' excludes). It lacks details on error handling or rate limits, but covers essential operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with every sentence adding value: the first states the purpose, the second explains usage with examples, and the third covers constraints and persistence. There is no wasted text, making it efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is largely complete: it explains what the tool does, how to use it, and key behaviors. It could improve by mentioning the tool's relationship to siblings like 'clear_filters' or expected output, but it adequately covers the core functionality and constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds minimal value beyond the schema by reinforcing the purpose of 'allow' and 'block' actions, but does not provide additional syntax or format details. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('configure domain filtering') and resource ('search results'), distinguishing it from siblings like 'clear_filters' and 'list_filters' by focusing on configuration rather than management or listing. It specifies the exact function of setting up domain-based filters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool (e.g., to prioritize trusted sources or exclude unreliable ones) and mentions persistence across searches, but it does not explicitly state when not to use it or name alternatives like 'recency_filter' for other filtering needs. Usage is implied but not exhaustively defined against all siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_filtersA

Display current filter configuration including allowed domains, blocked domains, and active recency setting. Useful for debugging search behavior.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what information is displayed (filter configuration details) and hints at a read-only operation ('Display'), but doesn't specify output format, potential errors, or any side effects. It adds some context about debugging utility, but lacks details on permissions or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences that are front-loaded with the core purpose and followed by a utility note. Every word adds value without repetition or fluff, making it highly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (0 parameters, no annotations, no output schema), the description is reasonably complete for a read-only configuration display tool. It specifies what information is included and the debugging context, but lacks details on output format or error handling, which could be helpful for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, earning a baseline score of 4 for not introducing confusion or redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Display current filter configuration' with specific components listed (allowed domains, blocked domains, recency setting). It uses a specific verb ('Display') and identifies the resource ('filter configuration'), but doesn't explicitly distinguish it from sibling tools like 'domain_filter' or 'recency_filter' that might modify these settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied usage guidance by stating it's 'Useful for debugging search behavior,' suggesting it should be used when troubleshooting search issues. However, it doesn't explicitly state when to use this tool versus alternatives like 'search' or the various filter-modifying siblings, nor does it provide any exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

model_infoA

View available Perplexity models and their specializations, or manually override model selection. By default, models are auto-selected based on query intent (research, reasoning, general search).

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoOptional: Override auto-selection. 'sonar-deep-research' for comprehensive analysis, 'sonar-reasoning-pro' for complex logic, 'sonar' for quick lookups

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: viewing available models, their specializations, and the ability to override auto-selection. It explains the default behavior (auto-selection based on query intent) and the override capability, though it doesn't specify what happens when no parameter is provided (e.g., whether it returns a list or default info).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose in the first clause. Both sentences earn their place: the first establishes what the tool does, and the second explains the default behavior and context. There's no wasted language or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (1 optional parameter with full schema coverage, no output schema), the description is mostly complete. It covers purpose, usage, and parameter context well. However, it doesn't specify what the tool returns (e.g., a list of models with details or just confirmation), which would be helpful since there's no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the context of the parameter: 'manually override model selection' and 'By default, models are auto-selected based on query intent'. This provides semantic meaning beyond the schema's enum descriptions, helping the agent understand when and why to use the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('View available Perplexity models and their specializations, or manually override model selection') and distinguishes it from sibling tools like 'search' or 'list_filters' by focusing on model information and selection rather than filtering or searching operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides usage guidance: 'By default, models are auto-selected based on query intent (research, reasoning, general search)' and indicates when to use the override parameter. This clearly distinguishes it from the default auto-selection behavior and helps the agent understand when manual selection is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recency_filterA

Control the time window for search results. Essential for time-sensitive queries like news, updates, or recent developments. Filter persists until changed.

ParametersJSON Schema
NameRequiredDescriptionDefault
filterYesTime window: 'hour' for breaking news, 'day' for daily updates, 'week' for recent developments, 'month' for broader recent context, 'none' to include all time periods

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important behavioral traits: the filter persists until changed (stateful behavior), and it's for search results (context of application). However, it doesn't mention potential side effects, error conditions, or what happens when the filter is applied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise with three sentences that each earn their place: states the core function, provides usage context, and reveals important behavioral trait (persistence). No wasted words, front-loaded with the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (stateful filter setting), no annotations, and no output schema, the description does reasonably well. It explains what the tool does, when to use it, and a key behavioral aspect (persistence). However, it doesn't describe what the tool returns or potential error conditions, leaving some gaps in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage and only 1 parameter, the schema already fully documents the parameter. The description adds some value by explaining why you'd use different time windows ('breaking news', 'daily updates', etc.), but doesn't provide additional syntax or format details beyond what's in the schema. For a single-parameter tool with excellent schema coverage, this is above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('Control the time window for search results') and distinguishes it from siblings by focusing on time-based filtering. It explicitly mentions what it does (sets a time window filter) rather than just restating the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('Essential for time-sensitive queries like news, updates, or recent developments'), but doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools. It implies usage scenarios but lacks explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv1.0.0
    • First observedclear_filters
    • First observeddomain_filter
    • First observedlist_filters
    • First observedmodel_info
    • First observedrecency_filter
    • First observedsearch

TDQS

A4.3/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: clear_filters removes filters, domain_filter configures domains, list_filters displays current settings, model_info shows models, recency_filter controls time windows, and search performs web searches. The descriptions reinforce these unique roles, making misselection unlikely.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case (e.g., clear_filters, domain_filter, list_filters, model_info, recency_filter, search). The naming is predictable and readable throughout, with no deviations or mixed conventions.

Tool Count5/5

With 6 tools, this server is well-scoped for its purpose of configuring and executing Perplexity AI searches. Each tool earns its place by covering essential aspects like filtering, model selection, and search execution, without being overly sparse or bloated.

Completeness5/5

The tool set provides complete coverage for the domain of Perplexity AI search configuration and execution. It includes setup (filters, model info), control (recency, domain filters), status (list_filters), and core functionality (search), with no obvious gaps that would cause agent failures.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
    2
    502
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    An MCP server that enables AI assistants to perform web searches on Perplexity.ai using browser automation instead of an official API. It supports persistent authenticated sessions and returns search results along with cited sources directly to the client.
    3
    49
    9
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/RossH121/perplexity-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server