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

ADMIN Panel

Log View

OpenAI Playground

MCP Integration

• 2026-02-01: Added automatic fallback mechanism (downgrades to anonymous mode when tokens fail); added real-time log viewing.
• 2026-01-19: Added SKILL support (.claude/skills/perplexity-search).
• 2026-01-16: Refactored project structure; added OpenAI endpoint adaptation.
• 2026-01-13: Added heartbeat detection to monitor token health periodically and send notifications via Telegram.
• 2026-01-03: Added WebUI control.
• 2026-01-02: Added multi-token pool support with dynamic management (list/add/remove).
• 2026-01-02: MCP responses now include a sources field with search result links.
• 2025-12-31: Added health check endpoint: http://127.0.0.1:8000/health.

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
  },
  "tokens": [
    {
      "id": "account1@example.com",
      "csrf_token": "your-csrf-token-1",
      "session_token": "your-session-token-1"
    },
    {
      "id": "account2@example.com",
      "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

Periodically checks token health and notifies via Telegram:

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

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

# Start services
docker compose up -d

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:-}
      # - SOCKS_PROXY=${SOCKS_PROXY:-}
    volumes:
      # 挂载 token 池配置文件
      - ./token_pool_config.json:/app/token_pool_config.json
    restart: unless-stopped

MCP_PORT=8000
MCP_TOKEN=sk-123456
PPLX_ADMIN_TOKEN=your-admin-token

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

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

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

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

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
  }'

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

1. Settings → AI Provider → Add Custom Provider
2. Fill in:
   • API Host: http://127.0.0.1:8000
   • API Key: sk-123456
3. Select model: perplexity-search or perplexity-reasoning

perplexity/
├── server/                  # MCP Server module
│   ├── __init__.py
│   ├── main.py              # Entry point
│   ├── app.py               # FastMCP app, auth, core logic
│   ├── mcp.py               # MCP tools
│   ├── oai.py               # OpenAI compatible API
│   ├── admin.py             # Admin endpoints
│   ├── utils.py             # Server utils
│   ├── client_pool.py       # Multi-account pool
│   └── web/                 # Web UI (React + Vite)
├── client.py                # Low-level API client
├── config.py                # Config constants
├── exceptions.py            # Custom exceptions
├── logger.py                # Logging config
└── utils.py                 # General utils

Skills are located in .claude/commands/pp/.

Usage:

• /pp:query <question> - Quick search
• /pp:reasoning <question> - Reasoning mode
• /pp:research <question> - Deep research

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