Perplexica

You run an MCP server that exposes Perplexica’s AI-powered search through multiple transports, letting clients connect via stdio, Server-Sent Events (SSE), or Streamable HTTP. This makes it easy to build interactive search experiences into your tools and IDEs while keeping a single, production-ready server implementation.

How to use

Connect to the Perplexica MCP Server using your preferred MCP client transport. You can run the server locally with stdio for desktop IDE integrations, or expose it over SSE or Streamable HTTP for web apps and other clients. Use the predefined environment variables to configure backend access and default models, and override them per request if needed.

How to install

Prerequisites you need before installing:
- Python installed on your system
- uvicorn available for serving SSE and HTTP transports
- uvx installed for running the MCP server via stdio or from source
- Docker and Docker Compose if you plan to deploy with Docker
- A Perplexica backend API accessible at a URL you control (for example, http://localhost:3000/api/search)

Install from PyPI (recommended):
- Run: `pip install perplexica-mcp`
- Optional: run help to see available commands with `uvx perplexica-mcp --help

Install from source (when you prefer building from repository):

• Clone the repository
• Install dependencies with your environment’s package manager (for example, uv sync to install Python dependencies)

Configuration and operation notes

Environment variables you commonly configure (and their defaults, where provided):

• PERPLEXICA_BACKEND_URL: URL to Perplexica search API
• PERPLEXICA_CHAT_MODEL_PROVIDER and PERPLEXICA_CHAT_MODEL_NAME: default chat model
• PERPLEXICA_EMBEDDING_MODEL_PROVIDER and PERPLEXICA_EMBEDDING_MODEL_NAME: default embedding model Values can be set in your shell or in a .env file, and can be overridden per request.

Transports supported by the server:

• Stdio: best for local MCP clients and IDE integrations
• SSE: suitable for web-based clients and real-time updates
• Streamable HTTP: REST-like transport for HTTP-based MCP clients

Common commands to run the server in different modes:
- Stdio (PyPI installation):
  `uvx perplexica-mcp stdio`
- Stdio (from source):
  `uv run src/perplexica_mcp/server.py stdio`
- SSE (from PyPI):
  `uvx perplexica-mcp sse`
- SSE (from source):
  `uv run src/perplexica_mcp/server.py sse`
- Streamable HTTP (from PyPI):
  `uvx perplexica-mcp http`
- Streamable HTTP (from source):
  `uv run src/perplexica_mcp/server.py http

Docker deployment

Docker support is provided for production deployments. You create a dedicated external network for backend integration and run separate containers for HTTP and SSE transports. Use docker-compose to build and run the containers.

Troubleshooting

If the server fails to start, verify that uvx (or uv for source) is installed and the command path is correct. If connections are refused, confirm the Perplexica backend URL is reachable and the environment variables are correctly set. Check permissions for the MCP client to execute the server, and ensure environment variables are loaded when starting the server.

Example connection configurations

{
  "mcpServers": {
    "perplexica_http": {
      "type": "http",
      "name": "perplexica_http",
      "url": "http://localhost:3002/mcp",
      "args": []
    },
    "perplexica_stdio_claude": {
      "type": "stdio",
      "name": "perplexica_stdio_claude",
      "command": "uvx",
      "args": ["perplexica-mcp", "stdio"],
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

Available tools

search

Performs AI-powered search over web, academic, and discussions sources with optional streaming and model configurations.