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 search with multiple source types (web, academic, discussions)
• 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

Development Environment

For Claude Code Users

Important: If you are using Claude Code for development, this project requires the use of the container-use MCP server for all development operations. All file operations, code changes, and shell commands must be executed within container-use environments.

Working with Container-Use (Claude Code Only)

When contributing to this project using Claude Code, you must:

1. Use Container-Use Only: All file operations, code editing, and shell commands must be performed using container-use environments
2. View Your Work: After making changes, inform others how to access your work:
   • Use container-use log <env_id> to view the development log
   • Use container-use checkout <env_id> to check out your environment
3. No Local Operations: Do not perform file operations directly on the local filesystem

Example Development Workflow (Claude Code)

# Create a new environment for your work
container-use create --title "Your feature description"

# Make your changes using container-use tools
# (All file operations handled by container-use)

# Share your work with others
container-use log <your-env-id>
container-use checkout <your-env-id>

This ensures consistency, reproducibility, and proper version control for all development activities when using Claude Code.

For Other Development Environments

If you are not using Claude Code, you can develop normally using your preferred tools and IDE. The container-use requirement does not apply to regular development workflows.

Installation

From PyPI (Recommended)

# 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.

Important: All transport modes require proper environment variable configuration, especially:

• PERPLEXICA_BACKEND_URL: URL to your Perplexica backend API
• PERPLEXICA_CHAT_MODEL_PROVIDER and PERPLEXICA_CHAT_MODEL_NAME: Chat model configuration
• PERPLEXICA_EMBEDDING_MODEL_PROVIDER and PERPLEXICA_EMBEDDING_MODEL_NAME: Embedding model configuration

These variables must be set either in your environment or provided in the MCP client configuration.

Claude Desktop

Stdio Transport (Recommended)

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",
        "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"
      }
    }
  }
}

Alternative (from source):

{
  "mcpServers": {
    "perplexica": {
      "command": "uv",
      "arg

... [View full README on GitHub](https://github.com/thetom42/perplexica-mcp#readme)