Perplexity Ai

Thanks for LINUX DO

Perplexity MCP Server

[](README-zh.md)

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.

Screenshots

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

Log View

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

MCP Integration

Changelog

• 2026-05-21: v1.9.5 — Add agent-friendly MCP aliases for quick ask, web search, reasoning, and deep research; improve tool descriptions and tests.
• 2026-03-10: v1.9.4 — Refresh the supported model lineup: add GPT-5.4 / GPT-5.4 Thinking, remove GPT-5.2 and Grok 4.1 variants, and sync MCP, OpenAI model exposure, tests, and docs.
• 2026-02-20: v1.9.1 — Fix frontend version display: sync package.json version so admin UI shows correct MANAGER_vX.X.X.
• 2026-02-20: v1.9.0 — Playground file attachment improvements: clipboard image paste (Ctrl+V) support; image files now show inline thumbnail previews in the input area.
• 2026-02-20: v1.8.1 — Added OAI file upload support: /v1/chat/completions now accepts input_file content parts (file_data, file_url, file_id); added Files API (POST/GET/DELETE /v1/files); added file attachment UI in playground.
• 2026-02-20: v1.8.0 — Simplified OAI model naming: pro mode models use base names (e.g. gpt-5-2), reasoning mode unified with -thinking suffix (e.g. gpt-5-2-thinking). Breaking change: old IDs like gpt-5-2-search, gpt-5-2-thinking-reasoning are no longer valid.
• 2026-02-20: Updated model options — added Claude 4.6 Sonnet and Gemini 3.1 Pro, removed Claude 4.5 and Gemini 3.0.
• 2026-02-16: Added global incognito toggle — force all queries to run in incognito mode via Admin UI or API.
• 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.

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": "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

Heartbeat Configuration (Optional)

Periodically checks token health and notifies via Telegram:

| Option | Description | |--------|-------------| | enable | Enable heartbeat checks | | question | Question used for testing | | interval | Check interval (in hours) | | tg_bot_token | Telegram Bot Token | | tg_chat_id | Telegram Chat ID |

Fallback Configuration (Optional)

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

| Option | Description | |--------|-------------| | fallback_to_auto | Enable fallback to anonymous mode (default true) |

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:

| Option | Description | |--------|-------------| | enabled | Force incognito mode for all queries (default false) |

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

.env Variables

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

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

| Tool | When to use | |------|-------------| | perplexity_ask | Quick general questions using low-cost auto mode | | perplexity_search | Current web search with Pro mode and web sources | | perplexity_reason | Multi-step reasoning with the default reasoning model | | perplexity_research | Slower, comprehensive deep research | | search | Parameterized auto/pro search with model, source, language, file, and fallback controls | | research | Parameterized reasoning/deep research with model, source, language, file, and fallback controls | | list_models | Inspect supported modes and model mappings |

OpenAI Compatible Endpoints

Base URL: http://127.0.0.1:8000/v1 Authorization: Bearer

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"}],
    "stream": true
  }'

Supported Models

| Model ID | Mode | Description | |----------|------|-------------| | Search Mode | | | | perplexity-search | pro | Default search model | | sonar | pro | Sonar model | | gpt-5-4 | pro | GPT-5.4 | | claude-4-6-sonnet | pro | Claude 4.6 Sonnet | | gemini-3-1-pro | pro | Gemini 3.1 Pro | | Thinking Mode | | | | perplexity-thinking | reasoning | Default thinking model | | gpt-5-4-thinking | reasoning | GPT-5.4 Thinking | | claude-4-6-sonnet-thinking | reasoning | Claude 4.6 Sonnet Thinking | | gemini-3-1-pro-thinking | reasoning | Gemini 3.1 Pro Thinking | | kimi-k2-thinking | reasoning | Kimi K2 Thinking | | Deep Research Mode | | | | perplexity-deepsearch | deep research | Deep research model |

Client Configuration (e.g., ChatBox)

1. Settings → AI Provider → Add Custom Provider
2. Fill in:

• API Host: http://127.0.0.1:8000
• API Key: sk-123456

1. Select model: perplexity-search or perplexity-thinking

Project Structure

perplexity/
├── server/                  # MCP Server module
│   ├── __init__.py
│   ├── main.py              # Entry point
│   ├── app.py               # FastMCP app, auth, core logic
│   ├── mcp.py               # MCP tools and agent-friendly aliases
│   ├── 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

Claude Code Integration

https://github.com/escapeWu/skills/blob/main/skills/perplexity-search/SKILL.md

Star History

[](https://star-history.com/#escapeWu/perplexity-ai&Date)

Upstream Project

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: escapeWu
• Source: escapeWu/perplexity-ai
• License: MIT
• Homepage: https://perplexity.ai

Install and usage instructions live in the source repository linked above.