perplexica

Perplexica MCP Server exposes a suite of AI-powered search and writing capabilities through the MCP framework. It includes Web Search, Academic Search, YouTube Search, Reddit Search, and a Writing Assistant, with support for multiple models and embedding providers. The server is designed to connect to a Perplexica backend at a local or remote base URL and can augment searches with OpenAI or other providers if configured. You can interact with the MCP API locally via the stdio transport when running in the documented configuration, enabling clients to query the search and writing features, and to leverage multi-model support for different chat and embedding models. The configuration options let you tailor the default providers and models (chat and embedding) to fit your environment and API keys.

To use, start the server with the provided Python module entry point and ensure the Perplexica backend is reachable (default http://localhost:3000). You can then send MCP requests (e.g., search, summarize, or write assistance prompts) to the server and receive structured responses. If you enable the OpenAI-based enhancements, provide the necessary API keys and base URLs in the environment configuration. The server also supports an option to switch transport to stdio for local development and testing.

Prerequisites:

• Python 3.10+
• A running Perplexica instance (default: http://localhost:3000)
• Optional: OpenAI API key for enhanced search capabilities

Installation steps:

1. Clone the repository
2. Install dependencies:

pip install -r requirements.txt
pip install .

or for development tooling:

uv tool install .

3. Ensure Perplexica backend is accessible at the configured base URL (default http://localhost:3000).
4. Configure the MCP server using the provided configuration examples (Python or uvx) and start the server as described in the starting guidance.

Development setup:

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

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

Starting the server (example):

python -m perplexica_mcp_server.server

Testing:

python test/test_client.py

python test/test_official_api.py

Tips and notes:

• Ensure PERPLEXICA_BASE_URL points to your Perplexica instance if different from default.
• If using enhanced OpenAI features, supply PERPLEXICA_CUSTOM_OPENAI_KEY and PERPLEXICA_CUSTOM_OPENAI_BASE_URL in the environment.
• The default timeout is 60 seconds; increase if you experience slow responses due to network or backend load.
• The server supports multiple output formats (json, formatted). The default is json.
• If you switch to uvx (uv) for Python packaging, ensure the uvx tool is installed and properly configured.
• For production deployments, consider configuring authentication and additional security hardening around the MCP endpoints.