Thanks for LINUX DO

Perplexity MCP Server

An unofficial Perplexity.ai server that exposes search capabilities through MCP (Model Context Protocol) and OpenAI-compatible endpoints. Supports multi-token pools for load balancing, health monitoring, and various search modes.

AGENT READ — Deployment

Read this section before advising on or executing deployment. A request for documentation, explanation, or review does not authorize a live deployment. Only change a server when the user explicitly asks to deploy, update, rebuild, restart, or roll out the service.

Route the request

Treat docker-compose.yml, .env.example, and deploy/compose.sh as the deployment sources of truth. The production entry point builds from the checked-out source; do not wait for or substitute a Docker Hub latest image.

First-install prerequisites

• Require Docker with the Compose plugin.
• Create .env and token_pool_config.json from their examples only when the destination files do not already exist. Generate a strong MCP_TOKEN (for example with openssl rand -hex 32).
• Keep .env, token_pool_config.json, data/, CSRF/session tokens, and admin tokens out of Git and command output. Never overwrite the server copies during an update.
• Preserve the mounted data/ directory so the model cache and WebUI/OAI/MCP session database survive container replacement.
• On an Internet-facing host, bind to a loopback address and place the service behind TLS/reverse proxying; see .env.example for the port form.

Run the guarded deployment entrypoint from the repository checkout:

./deploy/compose.sh config
./deploy/compose.sh up
./deploy/compose.sh verify
./deploy/compose.sh status

up validates .env and the non-empty token pool, builds the application image from the current checkout, replaces the service, waits for container health, calls /health, and prints status.

Production release contract

1. Review the intended local diff on main, commit only requested files, and push that exact commit.
2. Confirm local HEAD equals origin/main before touching the server.
3. Require a clean remote tracked worktree; use only a fast-forward pull and verify the remote SHA equals the recorded local commit.
4. Run ./deploy/compose.sh up, followed by verify and status.
5. Report the deployed commit, image ID, /health result, and final container state.

Stop on a dirty remote worktree, SHA mismatch, failed build, failed health check, or failed status check. Never force-push, run git reset/git clean, use docker compose down, delete images or volumes, or replace server secrets and persistent data as part of routine deployment.

Agent Search Skill

This repository includes .agents/skills/perplexity-search/SKILL.md as the default companion skill for Agents that need current public-web information. It provides a ready-to-run standard-library CLI, fixed Grok 4.6 Ask and Deep Research routing, cited output, and reusable native sessions without requiring Agents to construct REST requests manually.

Set PPLX_BASE_URL and MCP_TOKEN in the environment, then run from the repository root:

SKILL_DIR="$PWD/.agents/skills/perplexity-search"
python3 "$SKILL_DIR/scripts/cli.py" ask "What changed this week? Cite primary sources."

Use ask for focused current searches and research for broad multi-source investigations. The checked-in configuration is sanitized and contains no deployment credentials.

Screenshots

ADMIN Panel https://yourdomain.com/admin/

OpenAI Playground https://yourdomain.com/playground/

Getting Started

Docker Compose Deployment

1. Prepare Configuration

Copy and edit the configuration file:

cp token_pool_config-example.json token_pool_config.json

Edit token_pool_config.json with your Perplexity account tokens:

{
  "heart_beat": {
    "enable": true,
    "question": "What is the date today?",
    "interval": 6,
    "tg_bot_token": "your-telegram-bot-token",
    "tg_chat_id": "your-telegram-chat-id"
  },
  "fallback": {
    "fallback_to_auto": true
  },
  "incognito": {
    "enabled": false
  },
  "tokens": [
    {
      "id": "[email protected]",
      "csrf_token": "your-csrf-token-1",
      "session_token": "your-session-token-1"
    },
    {
      "id": "[email protected]",
      "csrf_token": "your-csrf-token-2",
      "session_token": "your-session-token-2"
    }
  ]
}

How to get tokens: Open perplexity.ai -> F12 Developer Tools -> Application -> Cookies

• csrf_token corresponds to next-auth.csrf-token
• session_token corresponds to __Secure-next-auth.session-token

Heartbeat Configuration (Recommand, handle cookie expire!)

Periodically checks token health and notifies via Telegram:

Fallback Configuration (Optional)

Automatically downgrades to anonymous Auto mode when all tokens are unavailable:

Incognito Configuration (Optional)

When enabled, forces all queries (MCP and OpenAI endpoints) to run in incognito mode, preventing search history from being saved on Perplexity accounts:

Can also be toggled at runtime via the Admin UI or POST /incognito/config API.

2. Start the Service

# Create .env file (optional)
cp .env.example .env

# Start services
docker compose up -d

docker-compose.yml Example

services:
  perplexity-mcp:
    image: shancw/perplexity-mcp:latest
    container_name: perplexity-mcp
    ports:
      - "${MCP_PORT:-8000}:8000"
    environment:
      - MCP_TOKEN=${MCP_TOKEN:-sk-123456}
      - PPLX_ADMIN_TOKEN=${PPLX_ADMIN_TOKEN:-}
      # - PPLX_SESSION_DB=/app/data/webui_sessions.sqlite3
      # - SOCKS_PROXY=${SOCKS_PROXY:-}
    volumes:
      # Mount the token pool and persistent daily model cache
      - ./token_pool_config.json:/app/token_pool_config.json
      - ./data:/app/data
    restart: unless-stopped

.env Variables

MCP_PORT=8000
MCP_TOKEN=sk-123456
PPLX_ADMIN_TOKEN=your-admin-token
# PPLX_SESSION_DB=./data/webui_sessions.sqlite3
# Optional outside Docker:
# PPLX_MODELS_CONFIG_URL=https://raw.githubusercontent.com/escapeWu/perplexity-ai/main/catalog/model_config_v2.json
# PPLX_MODEL_CACHE_PATH=./data/model_config_v2.json
# PPLX_MODEL_CACHE_TTL=86400

Multi-Token Pool (Load Balancing)

Configure multiple Perplexity account tokens to enable load balancing and high availability. See the "Prepare Configuration" section above for the JSON structure.

MCP Configuration

{
  "mcpServers": {
    "perplexity": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer sk-123456"
      }
    }
  }
}

MCP Tools

perplexity_ask_v2 defaults to perplexity-search when model is omitted. Its model values are the same IDs returned by /v1/models, for example gpt-5-6-terra; thinking: true selects the paired thinking model. Both v2 tools create a session when session_id is omitted and return it at the top level of the result:

{
  "status": "ok",
  "session_id": "sess_...",
  "model": "gpt-5-6-terra-thinking",
  "data": {"answer": "...", "sources": []}
}

The legacy tools list_models, search, research, perplexity_ask, perplexity_search, perplexity_reason, perplexity_research, and toggle_builtin_tools remain callable for compatibility, but are marked deprecated / pending_removal in MCP metadata and descriptions.

OpenAI Compatible Endpoints

Base URL: http://127.0.0.1:8000/v1 Authorization: Bearer <MCP_TOKEN>

Chat completions stream live upstream events by default. Pass "stream": false to wait for a complete JSON response. The Playground also requests optional Perplexity progress chunks so it can display analysis, web search, source review, and answer-writing stages. Other OpenAI clients can opt in with "perplexity": {"include_progress": true}; the extension is disabled by default for API compatibility.

Every valid chat-completions request is assigned a native conversation session. Omit session_id to start one, then read the top-level session_id from the JSON response. Streaming responses include the same value in every JSON SSE chunk and in the X-Session-ID response header. To continue, send that ID with only the current user turn:

{
  "model": "perplexity-search",
  "session_id": "sess_...",
  "messages": [{"role": "user", "content": "Now compare it with Tokyo"}],
  "stream": false
}

The first turn permanently binds the session to one compatible Perplexity account. Follow-ups reuse that account and the upstream native cursor; they never fail over to another account. An unknown session returns HTTP 404.

Examples

List Models

curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer sk-123456"

Chat Completions (Non-streaming)

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-123456" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perplexity-search",
    "messages": [{"role": "user", "content": "How is the weather today?"}],
    "stream": false
  }'

Chat Completions (Streaming)

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-123456" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perplexity-thinking",
    "messages": [{"role": "user", "content": "Analyze AI trends"}],
    "perplexity": {"include_progress": true}
  }'

Progress updates remain regular chat.completion.chunk events with an empty content delta and an additional perplexity_progress field. Clients that do not understand the extension can leave it disabled.

For catalog models that provide both regular and reasoning variants, pass "thinking": true while keeping the regular model ID. The server resolves the paired -thinking model before calling Perplexity:

{
  "model": "gpt-5-6-terra",
  "thinking": true,
  "messages": [{"role": "user", "content": "Analyze this problem"}]
}

Models without a reasoning variant return an invalid_request_error. reasoning_effort is intentionally rejected: Perplexity's web endpoint exposes reasoning through model selection and does not provide a verified effort control.

Supported Models

The repository publishes a validated Perplexity v2 model snapshot at catalog/model_config_v2.json. Servers fetch that snapshot from GitHub Raw every 24 hours and persist a local cache. /v1/models, MCP list_models, validation, and upstream model_preference routing all use that same catalog.

• Pro accounts expose Pro models.
• Max accounts expose both Pro and Max models.
• Max-only requests are routed only to Max accounts.
• Browser-agent entries are excluded because they do not use the search API.
• perplexity-search, perplexity-thinking, and perplexity-deepsearch remain stable default IDs. Use GET /v1/models for the current full list.

If the daily refresh fails, the last valid on-disk catalog remains active. Static built-in mappings are used only when no valid cache exists.

Star History

What's New

• 2026-08-16: v1.15.0 — Add OpenAI-aligned v2 MCP ask/research tools and REST session continuation with account-bound conversations, refresh the dynamic model catalog, deprecate legacy MCP tools, and align the Playground model and Thinking controls with Perplexity WebUI.
• 2026-08-13: v1.14.0 — Add server-backed Playground conversations with a responsive session sidebar, native Perplexity follow-up threads, persistent history, and immutable per-conversation account binding without cross-account failover.
• 2026-08-12: v1.13.3 — Upgrade curl-cffi browser fingerprints to stop Grok 4.5 and Claude Sonnet 5 requests from silently falling back to Best/turbo, and expose requested-versus-effective model metadata with a server warning when upstream downgrades recur.
• 2026-07-31: v1.13.2 — Prevent all explicitly selected models from being silently downgraded by matching Perplexity's current browser request protocol, and publish a validated Pro/Max model snapshot that servers refresh daily from GitHub Raw.
• 2026-07-30: v1.13.1 — Restore real-time Playground progress and answer streaming for Perplexity's new block-based response protocol, reconstruct offset Markdown chunks, and deduplicate repeated lifecycle stages.
• 2026-07-30: v1.13.0 — Add a daily cached Perplexity model catalog with Pro/Max-aware discovery and account routing, expose live model metadata in the Playground, and remove unused client-side SDK, account automation, Labs, examples, and legacy assets for server-only deployment.
• 2026-07-29: v1.12.0 — Add optional structured Perplexity progress events and a live Playground stage timeline, preserve partial output across stream failures and cancellation, and align service requests with the browser query_source required by current models.
• 2026-07-29: v1.11.0 — Stream OpenAI-compatible chat completions from upstream in real time by default, retain opt-in complete JSON responses with stream: false, add WebUI stream mode controls and working cancellation, and harden stream failover and cleanup.
• 2026-07-29: v1.10.1 — Close synchronous streaming responses reliably, move user-info network calls outside the pool lock, use starvation-free smooth weighted round-robin scheduling, sync runtime dependencies, and make Playground cancellation abort active requests.
• 2026-07-28: v1.10.0 — Add the current non-Max model lineup (Sonar 2, GPT-5.6 Terra, Gemini 3.1 Pro, Claude Sonnet 5, Kimi K3, GLM 5.2, Grok 4.5, and Nemotron 3 Ultra), centralize model mappings, and sync MCP/OpenAI discovery, tests, and docs.

Upstream Project

https://github.com/helallao/perplexity-ai

• fix param lack, auto redirect to GPT-5.6-nano, and add fancy mcp/restapi server