Skip to main content
Glama

Perplexica MCP Server

Perplexica MCP Server

A Model Context Protocol (MCP) server that provides search functionality using Perplexica's AI-powered search engine.

Features

  • Search Tool: AI-powered web search with multiple focus modes
  • Multiple Transport Support: stdio, SSE, and Streamable HTTP transports
  • FastMCP Integration: Built using FastMCP for robust MCP protocol compliance
  • Unified Architecture: Single server implementation supporting all transport modes
  • Production Ready: Docker support with security best practices

Installation

# Install directly from PyPI pip install perplexica-mcp # Or using uvx for isolated execution uvx perplexica-mcp --help

From Source

# Clone the repository git clone https://github.com/thetom42/perplexica-mcp.git cd perplexica-mcp # Install dependencies uv sync

MCP Client Configuration

To use this server with MCP clients, you need to configure the client to connect to the Perplexica MCP server. Below are configuration examples for popular MCP clients.

Claude Desktop

Add the following to your Claude Desktop configuration file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{ "mcpServers": { "perplexica": { "command": "uvx", "args": ["perplexica-mcp", "stdio"], "env": { "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search" } } } }

Alternative (from source):

{ "mcpServers": { "perplexica": { "command": "uv", "args": ["run", "/path/to/perplexica-mcp/src/perplexica_mcp.py", "stdio"], "env": { "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search" } } } }
SSE Transport

For SSE transport, first start the server:

uv run src/perplexica_mcp.py sse

Then configure Claude Desktop:

{ "mcpServers": { "perplexica": { "url": "http://localhost:3001/sse" } } }

Cursor IDE

Add to your Cursor MCP configuration:

{ "servers": { "perplexica": { "command": "uvx", "args": ["perplexica-mcp", "stdio"], "env": { "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search" } } } }

Alternative (from source):

{ "servers": { "perplexica": { "command": "uv", "args": ["run", "/path/to/perplexica-mcp/src/perplexica_mcp.py", "stdio"], "env": { "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search" } } } }

Generic MCP Client Configuration

For any MCP client supporting stdio transport:

# Command to run the server (PyPI installation) uvx perplexica-mcp stdio # Command to run the server (from source) uv run /path/to/perplexica-mcp/src/perplexica_mcp.py stdio # Environment variables PERPLEXICA_BACKEND_URL=http://localhost:3000/api/search

For HTTP/SSE transport clients:

# Start the server (PyPI installation) uvx perplexica-mcp sse # or 'http' # Start the server (from source) uv run /path/to/perplexica-mcp/src/perplexica_mcp.py sse # or 'http' # Connect to endpoints SSE: http://localhost:3001/sse HTTP: http://localhost:3002/mcp/

Configuration Notes

  1. Path Configuration: Replace /path/to/perplexica-mcp/ with the actual path to your installation
  2. Perplexica URL: Ensure PERPLEXICA_BACKEND_URL points to your running Perplexica instance
  3. Transport Selection:
    • Use stdio for most MCP clients (Claude Desktop, Cursor)
    • Use SSE for web-based clients or real-time applications
    • Use HTTP for REST API integrations
  4. Dependencies: Ensure uvx is installed and available in your PATH (or uv for source installations)

Troubleshooting

  • Server not starting: Check that uvx (or uv for source) is installed and the path is correct
  • Connection refused: Verify Perplexica is running and accessible at the configured URL
  • Permission errors: Ensure the MCP client has permission to execute the server command
  • Environment variables: Check that PERPLEXICA_BACKEND_URL is properly set

Server Configuration

Create a .env file in the project root with your Perplexica configuration:

PERPLEXICA_BACKEND_URL=http://localhost:3000/api/search

Usage

The server supports three transport modes:

1. Stdio Transport

# PyPI installation uvx perplexica-mcp stdio # From source uv run src/perplexica_mcp.py stdio

2. SSE Transport

# PyPI installation uvx perplexica-mcp sse [host] [port] # From source uv run src/perplexica_mcp.py sse [host] [port] # Default: localhost:3001, endpoint: /sse

3. Streamable HTTP Transport

# PyPI installation uvx perplexica-mcp http [host] [port] # From source uv run src/perplexica_mcp.py http [host] [port] # Default: localhost:3002, endpoint: /mcp

Docker Deployment

The server includes Docker support with multiple transport configurations for containerized deployments.

Prerequisites

  • Docker and Docker Compose installed
  • External Docker network named backend (for integration with Perplexica)

Create External Network

docker network create backend

Build and Run

Option 1: HTTP Transport (Streamable HTTP)
# Build and run with HTTP transport docker-compose up -d # Or build first, then run docker-compose build docker-compose up -d
Option 2: SSE Transport (Server-Sent Events)
# Build and run with SSE transport docker-compose -f docker-compose-sse.yml up -d # Or build first, then run docker-compose -f docker-compose-sse.yml build docker-compose -f docker-compose-sse.yml up -d

Environment Configuration

Both Docker configurations support environment variables:

# Create .env file for Docker cat > .env << EOF PERPLEXICA_BACKEND_URL=http://perplexica-app:3000/api/search EOF # Uncomment env_file in docker-compose.yml to use .env file

Or set environment variables directly in the compose file:

environment: - PERPLEXICA_BACKEND_URL=http://your-perplexica-host:3000/api/search

Container Details

TransportContainer NamePortEndpointHealth Check
HTTPperplexica-mcp-http3001/mcp/MCP initialize request
SSEperplexica-mcp-sse3001/sseSSE endpoint check

Health Monitoring

Both containers include health checks:

# Check container health docker ps docker-compose ps # View health check logs docker logs perplexica-mcp-http docker logs perplexica-mcp-sse

Integration with Perplexica

The Docker setup assumes Perplexica is running in the same Docker network:

# Example Perplexica service in the same compose file services: perplexica-app: # ... your Perplexica configuration networks: - backend perplexica-mcp: # ... MCP server configuration environment: - PERPLEXICA_BACKEND_URL=http://perplexica-app:3000/api/search networks: - backend

Production Considerations

  • Both containers use restart: unless-stopped for reliability
  • Health checks ensure service availability
  • External network allows integration with existing Perplexica deployments
  • Security best practices implemented in Dockerfile

Available Tools

Performs AI-powered web search using Perplexica.

Parameters:

  • query (string, required): Search query
  • focus_mode (string, required): One of 'webSearch', 'academicSearch', 'writingAssistant', 'wolframAlphaSearch', 'youtubeSearch', 'redditSearch'
  • chat_model (string, optional): Chat model configuration
  • embedding_model (string, optional): Embedding model configuration
  • optimization_mode (string, optional): 'speed' or 'balanced'
  • history (array, optional): Conversation history
  • system_instructions (string, optional): Custom instructions
  • stream (boolean, optional): Whether to stream responses

Testing

Run the comprehensive test suite to verify all transports:

uv run src/test_transports.py

This will test:

  • ✓ Stdio transport with MCP protocol handshake
  • ✓ HTTP transport with Streamable HTTP compliance
  • ✓ SSE transport endpoint accessibility

Transport Details

Stdio Transport

  • Uses FastMCP's built-in stdio server
  • Supports full MCP protocol including initialization and tool listing
  • Ideal for MCP client integration

SSE Transport

  • Server-Sent Events for real-time communication
  • Endpoint: http://host:port/sse
  • Includes periodic ping messages for connection health

Streamable HTTP Transport

  • Compliant with MCP Streamable HTTP specification
  • Endpoint: http://host:port/mcp
  • Returns 307 redirect to /mcp/ as per protocol
  • Uses StreamableHTTPSessionManager for proper session handling

Development

The server is built using:

  • FastMCP: Modern MCP server framework with built-in transport support
  • Uvicorn: ASGI server for SSE and HTTP transports
  • httpx: HTTP client for Perplexica API communication
  • python-dotenv: Environment variable management

Architecture

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ MCP Client │◄──►│ Perplexica MCP │◄──►│ Perplexica │ │ │ │ Server │ │ Search API │ │ (stdio/SSE/ │ │ (FastMCP) │ │ │ │ HTTP) │ │ │ │ │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────┐ │ FastMCP │ │ Framework │ │ ┌──────────┐ │ │ │ stdio │ │ │ │ SSE │ │ │ │ HTTP │ │ │ └──────────┘ │ └──────────────┘

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Support

For issues and questions:

  • Check the troubleshooting section
  • Review the Perplexica documentation
  • Open an issue on GitHub
Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server that acts as a proxy to provide LLM access to Perplexica's AI-powered search engine, enabling AI assistants to perform searches with various focus modes.

  1. Features
    1. Installation
      1. From PyPI (Recommended)
      2. From Source
    2. MCP Client Configuration
      1. Claude Desktop
      2. Cursor IDE
      3. Generic MCP Client Configuration
      4. Configuration Notes
      5. Troubleshooting
    3. Server Configuration
      1. Usage
        1. Stdio Transport
        2. SSE Transport
        3. Streamable HTTP Transport
      2. Docker Deployment
        1. Prerequisites
        2. Create External Network
        3. Build and Run
        4. Environment Configuration
        5. Container Details
        6. Health Monitoring
        7. Integration with Perplexica
        8. Production Considerations
      3. Available Tools
        1. search
      4. Testing
        1. Transport Details
          1. Stdio Transport
          2. SSE Transport
          3. Streamable HTTP Transport
        2. Development
          1. Architecture
            1. License
              1. Contributing
                1. Support

                  Related MCP Servers

                  • -
                    security
                    F
                    license
                    -
                    quality
                    A Model Context Protocol server that enables LLMs to interact with Elasticsearch clusters, allowing them to manage indices and execute search queries using natural language.
                    Last updated -
                    1
                    JavaScript
                  • -
                    security
                    F
                    license
                    -
                    quality
                    A Model Context Protocol server that provides AI assistants with structured access to your Logseq knowledge graph, enabling retrieval, searching, analysis, and creation of content within your personal knowledge base.
                    Last updated -
                    19
                    TypeScript
                    • Apple
                  • -
                    security
                    F
                    license
                    -
                    quality
                    A Model Context Protocol server that enables AI assistants like Claude to perform real-time web searches using the Exa AI Search API in a safe and controlled manner.
                    Last updated -
                    1,964
                    • Apple
                  • A
                    security
                    A
                    license
                    A
                    quality
                    A Model Context Protocol server that enables AI assistants to interact with Confluence content, supporting operations like retrieving, searching, creating, and updating pages and spaces.
                    Last updated -
                    9
                    3
                    TypeScript
                    MIT License

                  View all related MCP servers

                  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/thetom42/perplexica-mcp'

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