MCP Perplexica

MCP server proxy for Perplexica search API.

This server allows LLMs to perform web searches through Perplexica using the Model Context Protocol (MCP).

Features

🔍 Web search through Perplexica
📚 Multiple focus modes (web, academic, YouTube, Reddit, etc.)
⚡ Configurable optimization modes (speed, balanced, quality)
🔧 Customizable model configuration
📖 Source citations in responses
🚀 Multiple transport modes (stdio, SSE, Streamable HTTP)

Prerequisites

Python 3.11+
UV package manager
Running Perplexica instance

Installation

Clone the repository:

git clone https://github.com/Kaiohz/mcp-perplexica.git
cd mcp-perplexica

Install dependencies with UV:

uv sync

Create your environment file:

cp .env.example .env

Edit .env with your configuration:

# Perplexica API
PERPLEXICA_URL=http://localhost:3000

# Transport: stdio (default), sse, or streamable-http
TRANSPORT=stdio
HOST=127.0.0.1
PORT=8000

# Model configuration
DEFAULT_CHAT_MODEL_PROVIDER_ID=your-provider-id
DEFAULT_CHAT_MODEL_KEY=anthropic/claude-sonnet-4.5
DEFAULT_EMBEDDING_MODEL_PROVIDER_ID=your-provider-id
DEFAULT_EMBEDDING_MODEL_KEY=openai/text-embedding-3-small

Usage

Transport Modes

The server supports three transport modes:

Transport	Description	Use Case
`stdio`	Standard input/output	CLI tools, Claude Desktop
`sse`	Server-Sent Events over HTTP	Web clients
`streamable-http`	Streamable HTTP (recommended for production)	Production deployments

Running with Docker Compose

The easiest way to run both Perplexica and MCP Perplexica together:

# Copy and configure environment files
cp .env.example .env
cp .env.perplexica.example .env.perplexica

# Edit .env with your MCP Perplexica settings
# Edit .env.perplexica with your Perplexica settings

# Start services
docker compose up -d

This starts:

Perplexica on http://localhost:3000
MCP Perplexica connected to Perplexica

Running the MCP Server (without Docker)

Stdio mode (default)

uv run python src/main.py

SSE mode

TRANSPORT=sse PORT=8000 uv run python src/main.py

Streamable HTTP mode

TRANSPORT=streamable-http PORT=8000 uv run python src/main.py

Claude Desktop Configuration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "perplexica": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-perplexica", "python", "-m", "main"],
      "env": {
        "PERPLEXICA_URL": "http://localhost:3000",
        "TRANSPORT": "stdio",
        "DEFAULT_CHAT_MODEL_PROVIDER_ID": "your-provider-id",
        "DEFAULT_CHAT_MODEL_KEY": "anthropic/claude-sonnet-4.5",
        "DEFAULT_EMBEDDING_MODEL_PROVIDER_ID": "your-provider-id",
        "DEFAULT_EMBEDDING_MODEL_KEY": "openai/text-embedding-3-small"
      }
    }
  }
}

Claude Code Configuration

For HTTP-based transports, you can add the server to Claude Code:

# Start the server with streamable-http transport
TRANSPORT=streamable-http PORT=8000 uv run python -m main

# Add to Claude Code
claude mcp add --transport http perplexica http://localhost:8000/mcp

Available Tools

`search`

Perform a web search using Perplexica.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	The search query
`focus_mode`	string	No	Search focus: `webSearch`, `academicSearch`, `writingAssistant`, `wolframAlphaSearch`, `youtubeSearch`, `redditSearch`
`optimization_mode`	string	No	Optimization: `speed`, `balanced`, `quality`
`system_instructions`	string	No	Custom instructions for AI response
`chat_model_provider_id`	string	No	Override default chat model provider
`chat_model_key`	string	No	Override default chat model
`embedding_model_provider_id`	string	No	Override default embedding provider
`embedding_model_key`	string	No	Override default embedding model

Example:

Search for "latest developments in AI" using academic focus

Development

Install dev dependencies

uv sync --dev

Run tests

uv run pytest

Run linter

uv run ruff check .
uv run ruff format .
uv run black src/

Architecture

This project follows hexagonal architecture:

src/
├── main.py              # MCP server entry point
├── config.py            # Pydantic Settings
├── dependencies.py      # Dependency injection
├── domain/              # Business core (pure Python)
│   ├── entities.py      # Dataclasses
│   └── ports.py         # ABC interfaces
├── application/         # Use cases
│   ├── requests.py      # Pydantic DTOs
│   └── use_cases.py     # Business logic
└── infrastructure/      # External adapters
    └── perplexica/
        └── adapter.py   # HTTP client

License

MIT

MCP Perplexica

MCP Perplexica

Features

Prerequisites

Installation

Usage

Transport Modes

Running with Docker Compose

Running the MCP Server (without Docker)

Stdio mode (default)

SSE mode

Streamable HTTP mode

Claude Desktop Configuration

Claude Code Configuration

Available Tools

`search`

Development

Install dev dependencies

Run tests

Run linter

Architecture

License

Latest Blog Posts

MCP directory API