# Perplexity Ai

> A third-party Perplexity MCP/REST API implementation that leverages Pro accounts to provide unlimited quota for reasoning and deep search capabilities. Includes multi-account support.

- **Type:** MCP server
- **Install:** `agentstack add mcp-escapewu-perplexity-ai`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [escapeWu](https://agentstack.voostack.com/s/escapewu)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [escapeWu](https://github.com/escapeWu)
- **Source:** https://github.com/escapeWu/perplexity-ai
- **Website:** https://perplexity.ai

## Install

```sh
agentstack add mcp-escapewu-perplexity-ai
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Thanks for [LINUX DO](https://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:

```bash
cp token_pool_config-example.json token_pool_config.json
```

Edit `token_pool_config.json` with your Perplexity account tokens:

```json
{
  "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

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

# Start services
docker compose up -d
```

#### docker-compose.yml Example

```yml
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

```bash
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

```json
{
  "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
```bash
curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer sk-123456"
```

#### Chat Completions (Non-streaming)
```bash
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)
```bash
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`
3. 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](https://github.com/escapeWu)
- **Source:** [escapeWu/perplexity-ai](https://github.com/escapeWu/perplexity-ai)
- **License:** MIT
- **Homepage:** https://perplexity.ai

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-escapewu-perplexity-ai
- Seller: https://agentstack.voostack.com/s/escapewu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.