Skip to main content
Glama
tianmu

Perplexica MCP Server

by tianmu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Perplexica MCP Server

Language: English | 中文

A Model Context Protocol (MCP) server that provides access to Perplexica's AI-powered search engine capabilities.

Features

  • Web Search: General web search using AI

  • Academic Search: Search academic sources and papers

  • YouTube Search: Find and summarize YouTube videos

  • Reddit Search: Search Reddit discussions

  • Writing Assistant: Get help with writing and research

  • Multi-model Support: Use different chat and embedding models

  • Health Monitoring: Check service status and availability

Related MCP server: 4o-mini-search-mcp

Prerequisites

  • Python 3.10+

  • A running Perplexica instance (default: http://localhost:3000)

  • Optional: OpenAI API key for enhanced search capabilities

Installation

  1. Clone this repository

  2. Install dependencies:

    pip install -r requirements.txt
pip install .

    or

    uv tool install .

Configuration

cline

Configure the server to cline:

{
  "mcpServers": {
    "perplexica": {
      "command": "python",
      "args": [
        "-m", "perplexica_mcp_server.server"
      ],
      "env": {
        "PERPLEXICA_DEFAULT_CHAT_PROVIDER":"custom_openai",
        "PERPLEXICA_DEFAULT_CHAT_MODEL":"gpt-4.1",
        "PERPLEXICA_CUSTOM_OPENAI_BASE_URL":"https://api.poe.com/v1",
        "PERPLEXICA_CUSTOM_OPENAI_KEY":"your_api_key",
        "PERPLEXICA_DEFAULT_EMBEDDING_PROVIDER":"transformers",
        "PERPLEXICA_DEFAULT_EMBEDDING_MODEL":"xenova-bge-small-en-v1.5",
        "PERPLEXICA_OPTIMIZATION_MODE":"balanced",
        "PERPLEXICA_BASE_URL":"http://localhost:3000"
      },
      "timeout": 60,
      "transport": "stdio"
    }
  }
}

or

{
  "mcpServers": {
    "perplexica": {
      "command": "uvx",
      "args": [
        "perplexica-mcp-server"
      ],
      "env": {
        "PERPLEXICA_DEFAULT_CHAT_PROVIDER":"custom_openai",
        "PERPLEXICA_DEFAULT_CHAT_MODEL":"gpt-4.1",
        "PERPLEXICA_CUSTOM_OPENAI_BASE_URL":"https://api.poe.com/v1",
        "PERPLEXICA_CUSTOM_OPENAI_KEY":"your_api_key",
        "PERPLEXICA_DEFAULT_EMBEDDING_PROVIDER":"transformers",
        "PERPLEXICA_DEFAULT_EMBEDDING_MODEL":"xenova-bge-small-en-v1.5",
        "PERPLEXICA_OPTIMIZATION_MODE":"balanced",
        "PERPLEXICA_BASE_URL":"http://localhost:3000"
      },
      "timeout": 60,
      "transport": "stdio"
    }
  }
}

Development

Copy env.example to .env and modify as needed:

cp env.example .env
# Edit .env file to set your configuration

Starting the Server

Run the MCP server with stdio transport:

python -m perplexica_mcp_server.server

Testing

Test the server functionality:

python test/test_client.py

Run test for you perplexica:

python test/test_official_api.py

Output Formats

Supports two output formats:

  • json: Raw JSON data (default)

  • formatted: Human-readable formatted text

License

MIT License

Available Tools

7 tools
get_available_modelsA

Get available chat and embedding models from Perplexica.

Returns: JSON string containing available models

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

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

No annotations exist, so the description carries the full burden. It states it returns a JSON string, but does not disclose any additional behavioral traits like caching 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 sentences, front-loaded, and contains no superfluous information. Every word adds value.

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?

For a simple tool with no parameters and an output schema, the description is adequately complete. It mentions the return type (JSON string) and source.

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?

There are zero parameters, so schema coverage is 100% and baseline is 4. The description does not need to add parameter information.

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 retrieves available chat and embedding models from Perplexica, using a specific verb ('Get') and resource. It distinguishes from sibling search and writing tools.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions.

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

health_checkA

Check if Perplexica API is healthy and accessible.

Returns: JSON string with health status

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

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

No annotations are provided, so the description carries the burden. It states the return format (JSON string with health status) but does not discuss side effects or read-only nature. Minimal but accurate.

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?

Two short sentences, front-loaded with purpose. Every word earns its place with no fluff.

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 there are no parameters and an output schema exists, the description covers the tool's purpose and return format completely. No additional details are necessary.

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?

There are no parameters, so schema coverage is effectively 100%. The description adds no parameter info, but none is needed. Baseline for 0 parameters is 4.

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 checks the health of the Perplexica API, using a specific verb ('Check') and resource ('Perplexica API'). It is functionally distinct from sibling tools like search or writing assistant.

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?

No explicit guidance on when to use this tool versus alternatives. However, the sibling tools are all different (search, writing), so the use case is implied but not formally stated.

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

search_academicC

Search academic sources using Perplexica's academic search mode.

Args: query: The academic search query chat_provider: Chat model provider (optional, uses env config if not provided) chat_model: Specific chat model to use (optional, uses env config if not provided) embedding_provider: Embedding model provider (optional, uses env config if not provided) embedding_model: Specific embedding model to use (optional, uses env config if not provided) optimization_mode: Speed vs quality tradeoff (optional, uses env config if not provided) output_format: Output format - "formatted" for human-readable text or "json" for raw JSON

Returns: Formatted text with AI response and sources, or JSON if output_format="json"

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
chat_providerNo
chat_modelNo
embedding_providerNo
embedding_modelNo
optimization_modeNo
output_formatNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It only mentions return format (formatted text or JSON) but omits critical behavioral traits: no mention of safety, idempotency, rate limits, or side effects. This is insufficient for an AI agent to anticipate consequences.

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

Conciseness4/5

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

The description uses a clear Args/Returns structure with each parameter on a separate line. There is no redundant wording, but optionality is restated for each parameter, slightly reducing efficiency. Overall, it is well-organized and front-loaded.

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 an output schema exists, the description omits precise return details but covers basics. However, it lacks completeness for a search tool: no mention of pagination, query constraints, or source types. With 7 parameters and no annotations, more context would be beneficial.

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?

Input schema coverage is 0%, so the description must compensate. It provides brief definitions for all 7 parameters, explaining optionality and fallback to env config. However, explanations are often tautological (e.g., 'query: The academic search query') and lack depth (e.g., 'Speed vs quality tradeoff' is vague). Adds moderate value.

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 it searches academic sources using a specialized mode. While it doesn't explicitly contrast with siblings like search_web or search_youtube, the phrase 'academic search mode' implies distinction. A score of 4 indicates good clarity but lacks explicit differentiation.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool vs alternatives. It does not mention use cases, exclusions, or prerequisites. The tool's purpose is stated, but the lack of usage context prevents effective selection among siblings.

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

search_redditB

Search Reddit discussions using Perplexica.

Args: query: The Reddit search query chat_provider: Chat model provider (optional, uses env config if not provided) chat_model: Specific chat model to use (optional, uses env config if not provided) optimization_mode: Speed vs quality tradeoff (optional, uses env config if not provided) output_format: Output format - "formatted" for human-readable text or "json" for raw JSON

Returns: Formatted text with AI response and sources, or JSON if output_format="json"

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
chat_providerNo
chat_modelNo
optimization_modeNo
output_formatNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/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 disclosing behavior. It fails to mention rate limits, authentication requirements, error handling, or whether the operation is read-only or destructive. The output format is noted but core behavioral traits are absent.

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

Conciseness4/5

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

The description is structured with Args and Returns sections, making it easy to parse. It is mostly concise but includes redundant parameter explanations that mirror the schema. The first sentence is direct, but the overall length could be reduced.

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 has 5 parameters (1 required) and no annotations, the description provides basic purpose and parameter semantics. It mentions the output format, and the presence of an output schema reduces the need to detail return values. However, it lacks usage context, examples, and limitations, leaving gaps for effective agent invocation.

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?

The description adds minimal meaning beyond the input schema by listing parameters in a docstring format, providing short explanations for each. However, schema coverage is 0% and the explanations are generic (e.g., 'optional, uses env config if not provided'), lacking specific constraints, examples, or default values.

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 searches Reddit discussions using Perplexica, with a specific verb (search) and resource (Reddit discussions). It distinguishes from sibling tools like search_web and search_youtube by specifying the target platform.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives such as search_web or search_academic. There are no scenarios, exclusions, or criteria mentioned, leaving the agent without context for selection.

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

search_webB

Search the web using Perplexica's AI-powered search engine.

Args: query: The search query or question chat_provider: Chat model provider (optional, uses env config if not provided) chat_model: Specific chat model to use (optional, uses env config if not provided) embedding_provider: Embedding model provider (optional, uses env config if not provided) embedding_model: Specific embedding model to use (optional, uses env config if not provided) optimization_mode: Speed vs quality tradeoff (optional, uses env config if not provided) output_format: Output format - "formatted" for human-readable text or "json" for raw JSON

Returns: Formatted text with AI response and sources, or JSON if output_format="json"

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
chat_providerNo
chat_modelNo
embedding_providerNo
embedding_modelNo
optimization_modeNo
output_formatNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

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

The description explains the output format (formatted text or JSON) and that it uses an AI-powered engine. No mention of rate limits, authentication, or safety (e.g., read-only). With no annotations, more detail would be beneficial.

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

Conciseness3/5

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

The description is well-structured with Args and Returns sections, but it is verbose, repeating 'optional, uses env config if not provided' for multiple parameters. Could be more concise.

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 parameter count and sibling tools, the description adequately explains parameters and return values. However, it lacks context on when to use this tool over similar search tools (e.g., search_academic), leaving the agent to infer.

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

Parameters5/5

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

Schema coverage is 0%, but the description provides detailed explanations for each parameter, clarifying defaults behavior ('uses env config if not provided') and the purpose of output_format. This adds significant value beyond the schema.

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 it searches the web using an AI-powered engine. However, it does not differentiate from sibling search tools like search_academic, search_reddit, or search_youtube, missing a chance to clarify scope.

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives such as search_academic or search_reddit. The description implies general web search but lacks explicit context or exclusions.

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

search_youtubeB

Search YouTube videos using Perplexica.

Args: query: The YouTube search query chat_provider: Chat model provider (optional, uses env config if not provided) chat_model: Specific chat model to use (optional, uses env config if not provided) optimization_mode: Speed vs quality tradeoff (optional, uses env config if not provided) output_format: Output format - "formatted" for human-readable text or "json" for raw JSON

Returns: Formatted text with AI response and sources, or JSON if output_format="json"

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
chat_providerNo
chat_modelNo
optimization_modeNo
output_formatNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavior. It explains return formats (formatted or JSON) but omits details about side effects, authentication needs, rate limits, or how Perplexica integrates. This is insufficient for a search tool that relies on external APIs.

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

Conciseness3/5

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

The description is front-loaded with the purpose, but the Args/Returns structure is verbose and slightly repetitive. It could be more concise by integrating parameter descriptions inline.

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 lack of annotations and output schema details (though output schema exists), the description covers the return format and parameters adequately. However, it does not explain the 'Perplexica' context or any behavioral constraints, leaving gaps for a complete understanding.

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 schema has 0% description coverage, but the description's Args section adds meaningful explanations for each parameter (e.g., 'The YouTube search query,' 'Chat model provider (optional, uses env config if not provided)'). This compensates for the schema gaps.

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 'Search YouTube videos using Perplexica,' indicating a specific verb and resource. However, it does not differentiate this tool from sibling tools like search_web or search_reddit, which would help clarify unique purpose.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It only lists parameters but lacks contextual usage advice.

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

writing_assistantC

Use Perplexica's writing assistant mode for writing help and research.

Args: query: The writing-related query or request chat_provider: Chat model provider (optional, uses env config if not provided) chat_model: Specific chat model to use (optional, uses env config if not provided) optimization_mode: Speed vs quality tradeoff (optional, uses env config if not provided) output_format: Output format - "formatted" for human-readable text or "json" for raw JSON

Returns: Formatted text with AI response and sources, or JSON if output_format="json"

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
chat_providerNo
chat_modelNo
optimization_modeNo
output_formatNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only mentions the mode and output formats, but lacks details like whether it can edit, generate, or has context limits. Minimal behavioral context.

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

Conciseness4/5

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

Well-structured with Args and Returns sections. Concisely covers parameters and output. Could be more front-loaded with the core purpose instead of repeating the tool name, but overall efficient.

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?

Provides basic information for usage (parameters, output format) but lacks context about what 'writing assistant mode' entails, example use cases, or limitations. Given 5 parameters and no annotations, the description is moderately complete.

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?

Input schema has 0% coverage (no descriptions), so the description compensates by listing each parameter with a brief definition. Descriptions like 'The writing-related query or request' add meaning, but some are generic (e.g., 'optional, uses env config'). Adequate but not detailed.

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 it provides writing help and research via Perplexica's writing assistant mode. It distinguishes from sibling search tools by focusing on general writing tasks rather than specific source searches.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool vs alternatives. While sibling tools are search-specific, the description lacks when-not-to-use advice or scenarios.

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.

  1. 7 tool updatesv0.1.0
    • First observedget_available_models
    • First observedhealth_check
    • First observedsearch_academic
    • First observedsearch_reddit
    • First observedsearch_web
    • First observedsearch_youtube
    • First observedwriting_assistant
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a clearly distinct functionality: health check, available models, and four different search sources (web, academic, Reddit, YouTube) plus a writing assistant. An agent can easily differentiate them.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with verb-noun structure (e.g., get_available_models, search_web) or clear noun phrases (e.g., health_check, writing_assistant). No mixing of conventions.

Tool Count5/5

With 7 tools, the set is well-scoped for a search and writing assistant server. It covers essential operations without being overwhelming or too sparse.

Completeness4/5

The tool surface covers the main search modes (web, academic, Reddit, YouTube), utility functions, and writing assistance. A minor gap is the lack of specific modes like image or news search, but the core workflow is well-supported.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers