Skip to main content
Glama
KaizenRose

perplexity-mcp

by KaizenRose
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Perplexity API Platform MCP Server

Install in Cursor   Install in VS Code   Add to Kiro   npm version

The official MCP server implementation for the Perplexity API Platform, providing AI assistants with real-time web search, reasoning, and research capabilities through Sonar models and the Search API.

Available Tools

perplexity_search

Direct web search using the Perplexity Search API. Returns ranked search results with metadata, perfect for finding current information.

perplexity_ask

General-purpose conversational AI with real-time web search using the sonar-pro model. Great for quick questions and everyday searches.

perplexity_research

Deep, comprehensive research using the sonar-deep-research model. Ideal for thorough analysis and detailed reports.

perplexity_reason

Advanced reasoning and problem-solving using the sonar-reasoning-pro model. Perfect for complex analytical tasks.

TIP

Available as an optional parameter forperplexity_reason and perplexity_research: strip_thinking

Set to true to remove <think>...</think> tags from the response, saving context tokens. Default: false

Related MCP server: Perplexity AI MCP Server

Configuration

Get Your API Key

  1. Get your Perplexity API Key from the API Portal

  2. Replace your_key_here in the configurations below with your API key

  3. (Optional) Set timeout: PERPLEXITY_TIMEOUT_MS=600000 (default: 5 minutes)

  4. (Optional) Set custom base URL: PERPLEXITY_BASE_URL=https://your-custom-url.com (default: https://api.perplexity.ai)

  5. (Optional) Set log level: PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR (default: ERROR)

Claude Code

claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Or install via plugin:

export PERPLEXITY_API_KEY="your_key_here"
claude
# Then run: /plugin marketplace add perplexityai/modelcontextprotocol
# Then run: /plugin install perplexity

Codex

codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Cursor, Claude Desktop, Kiro, Windsurf, and VS Code

Most clients can be configured manually using the same mcpServers wrapper in their client config (as shown for Cursor). If a client has a different schema, check its docs for the exact wrapper format.

For manual setup, these clients all use the same mcpServers structure:

Client

Config File

Cursor

~/.cursor/mcp.json

Claude Desktop

claude_desktop_config.json

Kiro

.kiro/settings/mcp.json

Windsurf

~/.codeium/windsurf/mcp_config.json

VS Code

.vscode/mcp.json

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

Proxy Setup (For Corporate Networks)

If you are running this server at work—especially behind a company firewall or proxy—you may need to tell the program how to send its internet traffic through your network's proxy. Follow these steps:

1. Get your proxy details

  • Ask your IT department for your HTTPS proxy address and port.

  • You may also need a username and password.

2. Set the proxy environment variable

The easiest and most reliable way for Perplexity MCP is to use PERPLEXITY_PROXY. For example:

export PERPLEXITY_PROXY=https://your-proxy-host:8080

If your proxy needs a username and password, use:

export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080

3. Alternate: Standard environment variables

If you'd rather use the standard variables, we support HTTPS_PROXY and HTTP_PROXY.

NOTE

The server checks proxy settings in this order:PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY. If none are set, it connects directly to the internet. URLs must include https://. Typical ports are 8080, 3128, and 80.

HTTP Server Deployment

For cloud or shared deployments, run the server in HTTP mode.

Environment Variables

Variable

Description

Default

PERPLEXITY_API_KEY

Your Perplexity API key

Required

PERPLEXITY_BASE_URL

Custom base URL for API requests

https://api.perplexity.ai

PORT

HTTP server port

8080

BIND_ADDRESS

Network interface to bind to. Defaults to loopback. Set to 0.0.0.0 to expose on all interfaces.

127.0.0.1

ALLOWED_ORIGINS

CORS origins (comma-separated). Defaults to empty (no cross-origin browser requests). Set to an explicit allowlist (e.g. https://app.example.com) or to * to allow any origin.

(empty)

ALLOWED_HOSTS

Additional Host header values to accept (comma-separated). Loopback hosts on PORT are always allowed. Add the public hostname when binding to 0.0.0.0.

(loopback only)

Docker

docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

Node.js

export PERPLEXITY_API_KEY=your_key_here
npm install && npm run build && npm run start:http

The server will be accessible at http://localhost:8080/mcp

Troubleshooting

  • API Key Issues: Ensure PERPLEXITY_API_KEY is set correctly

  • Connection Errors: Check your internet connection and API key validity

  • Tool Not Found: Make sure the package is installed and the command path is correct

  • Timeout Errors: For very long research queries, set PERPLEXITY_TIMEOUT_MS to a higher value

  • Proxy Issues: Verify your PERPLEXITY_PROXY or HTTPS_PROXY setup and ensure api.perplexity.ai isn't blocked by your firewall.

  • EOF / Initialize Errors: Some strict MCP clients fail because npx writes installation messages to stdout. Use npx -yq instead of npx -y to suppress this output.

For support, visit community.perplexity.ai or file an issue.

Available Tools

4 tools
perplexity_askAsk PerplexityA
Read-only

Answer a question using web-grounded AI (Sonar Pro model). Best for: quick factual questions, summaries, explanations, and general Q&A. Returns a text response with numbered citations. Fastest and cheapest option. Supports filtering by recency (hour/day/week/month/year), domain restrictions, and search context size. For in-depth multi-source research, use perplexity_research instead. For step-by-step reasoning and analysis, use perplexity_reason instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
messagesYesArray of conversation messages
search_context_sizeNoControls how much web context is retrieved. 'low' (default) is fastest, 'high' provides more comprehensive results.
search_domain_filterNoRestrict search results to specific domains (e.g., ['wikipedia.org', 'arxiv.org']). Use '-' prefix for exclusion (e.g., ['-reddit.com']).
search_recency_filterNoFilter search results by recency. Use 'hour' for very recent news, 'day' for today's updates, 'week' for this week, etc.

Output Schema

ParametersJSON Schema
NameRequiredDescription
responseYesAI-generated text response with numbered citation references

TDQS

A4.5/5.0
Behavior4/5

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

Annotations indicate read-only, open-world, non-destructive behavior. The description adds context beyond annotations: returns numbered citations, supports specific filter types, and notes speed/cost trade-offs. It does not contradict annotations, and the added behavioral details are valuable for expectation-setting.

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?

Every sentence earns its place: purpose, use cases, output format, performance, filters, and alternatives. It is front-loaded and clearly structured, with no wasted words despite covering multiple facets.

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

Completeness5/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, the presence of an output schema, and rich annotations, the description covers all essential aspects: operation, output, configuration, and tool differentiation. It is fully sufficient for an agent to select and invoke the tool correctly.

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 parameter semantics are already documented. The description restates filter types (recency, domain, context size) but does not meaningfully enrich beyond the schema's own descriptions. Baseline 3 is appropriate because the schema carries the burden.

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 opens with a specific verb and resource: 'Answer a question using web-grounded AI (Sonar Pro model).' It clearly contrasts with sibling tools by naming perplexity_research and perplexity_reason, making the tool's specific role unmistakable.

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?

Provides explicit 'Best for' scenarios (quick factual questions, summaries, explanations, general Q&A), performance expectations ('Fastest and cheapest'), and direct alternatives ('For in-depth multi-source research, use perplexity_research instead'). This gives agents clear when-to-use and when-not-to-use guidance.

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

perplexity_reasonAdvanced ReasoningA
Read-only

Analyze a question using step-by-step reasoning with web grounding (Sonar Reasoning Pro model). Best for: math, logic, comparisons, complex arguments, and tasks requiring chain-of-thought. Returns a reasoned response with numbered citations. Supports filtering by recency (hour/day/week/month/year), domain restrictions, and search context size. For quick factual questions, use perplexity_ask instead. For comprehensive multi-source research, use perplexity_research instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
messagesYesArray of conversation messages
strip_thinkingNoIf true, removes <think>...</think> tags and their content from the response to save context tokens. Default is false.
search_context_sizeNoControls how much web context is retrieved. 'low' (default) is fastest, 'high' provides more comprehensive results.
search_domain_filterNoRestrict search results to specific domains (e.g., ['wikipedia.org', 'arxiv.org']). Use '-' prefix for exclusion (e.g., ['-reddit.com']).
search_recency_filterNoFilter search results by recency. Use 'hour' for very recent news, 'day' for today's updates, 'week' for this week, etc.

Output Schema

ParametersJSON Schema
NameRequiredDescription
responseYesAI-generated text response with numbered citation references

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds useful behavioral context beyond annotations, such as the reasoning model ('Sonar Reasoning Pro model'), the step-by-step nature of the analysis, and the presence of numbered citations in the output. These details help the agent anticipate response style and value. However, it doesn't explicitly mention potential latency or token usage, which could be relevant for a reasoning-heavy tool.

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 concise and well-structured, with four sentences covering purpose, usage cases, output features, and alternatives. It is front-loaded with the core function and uses no filler. Every sentence adds valuable information, making the description efficient and easy to parse.

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

Completeness5/5

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

Given the tool's complexity (5 params, output schema, annotations), the description is complete: it covers what the tool does, when to use it, when not to use it, and what to expect in the response. The output schema exists, so return values need not be described. The combination of annotations, schema, and description provides a comprehensive picture.

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%, with all 5 parameters thoroughly documented in the schema. The description mentions 'Supports filtering by recency (hour/day/week/month/year), domain restrictions, and search context size,' which echoes schema properties without adding new semantic depth. It does not explain parameter interactions or provide extra context beyond the schema, so a baseline score of 3 is appropriate.

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 function: 'Analyze a question using step-by-step reasoning with web grounding (Sonar Reasoning Pro model).' It distinguishes itself from siblings by specifying its niche: 'Best for: math, logic, comparisons, complex arguments, and tasks requiring chain-of-thought.' It also notes the return format: 'Returns a reasoned response with numbered citations.' This is a specific verb+resource+scope with clear differentiation.

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 provides explicit usage guidance, stating 'For quick factual questions, use perplexity_ask instead. For comprehensive multi-source research, use perplexity_research instead.' It also lists ideal use cases ('Best for: math, logic, comparisons...'), giving the agent clear criteria for when to choose this tool over alternatives.

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

perplexity_researchDeep ResearchA
Read-only

Conduct deep, multi-source research on a topic (Sonar Deep Research model). Best for: literature reviews, comprehensive overviews, investigative queries needing many sources. Returns a detailed response with numbered citations. Significantly slower than other tools (30+ seconds). For quick factual questions, use perplexity_ask instead. For logical analysis and reasoning, use perplexity_reason instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
messagesYesArray of conversation messages
strip_thinkingNoIf true, removes <think>...</think> tags and their content from the response to save context tokens. Default is false.
reasoning_effortNoControls depth of deep research reasoning. Higher values produce more thorough analysis.

Output Schema

ParametersJSON Schema
NameRequiredDescription
responseYesAI-generated text response with numbered citation references

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, so the description's addition of 'Significantly slower than other tools (30+ seconds)' and 'Returns a detailed response with numbered citations' provides valuable behavioral context beyond the structured metadata. It does not contradict the read-only nature.

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 a compact set of five purposeful sentences. It front-loads the core action, then provides use cases, output format, a performance warning, and sibling alternatives—all without redundancy or filler.

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?

With an output schema present and annotations providing read-only safety, the description gives sufficient context: purpose, use cases, speed, and alternatives. It is complete for a research tool, though it could mention specific limitations of the underlying model or cite that responses are not real-time.

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 coverage is 100%, so the baseline is 3. The description does not describe parameters directly, but the schema already documents messages, strip_thinking, and reasoning_effort with their meanings. The description's reference to 'deep research' implicitly aligns with reasoning_effort, but adds no new parameter-level detail.

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 conducts deep, multi-source research on a topic, and explicitly distinguishes it from siblings by naming alternatives for quick facts and logical reasoning. It also adds concrete output characteristics like numbered citations.

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?

Explicit when-to-use guidance is provided: 'Best for literature reviews, comprehensive overviews, investigative queries needing many sources.' It also clearly states when NOT to use it ('quick factual questions' -> use perplexity_ask; logical analysis -> use perplexity_reason) and warns about the 30+ second latency.

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. 4 tool updatesv0.9.0
    • First observedperplexity_ask
    • First observedperplexity_reason
    • First observedperplexity_research
    • First observedperplexity_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: ask for quick Q&A, research for deep multi-source, reason for step-by-step analysis, and search for raw results. The descriptions explicitly cross-reference each other to guide selection, eliminating ambiguity.

Naming Consistency5/5

All tool names follow the consistent pattern 'perplexity_' plus a distinct verb (ask, research, reason, search). Naming is uniform, lowercase, and underscores are used consistently.

Tool Count5/5

Four tools is an ideal scope for a search/answer server. Each tool covers a different mode (quick, deep, reasoning, raw) with no redundancy, and the count feels complete without being bloated.

Completeness5/5

The tool surface covers the full spectrum from raw search results to AI-synthesized quick answers, deep research, and reasoning. There are no obvious dead ends; citations and source info are included in outputs.

Maintenance

ActivityStale
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

  • Perplexity AI MCP Server

    mkusaka
    A
    license
    B
    quality
    D
    maintenance
    An MCP server integrating Perplexity AI's API to offer advanced search capabilities with support for multiple models and result configuration.
    1
    1,014
    1
    MIT

  • MCP Perplexity Pro

    cfdude
    A
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive MCP server that provides intelligent access to Perplexity AI's search and reasoning models with automatic model selection, conversation management, and project-aware storage. Supports real-time search, deep research, chat sessions, and async operations for complex queries.
    29
    3
    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/KaizenRose/perplexity-mcp'

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