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 image
Log View image
OpenAI Playground img_v3_02u3_eada7873-379e-42c1-bcbf-3c0466a66ffg
MCP Integration image
- 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
sourcesfield 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_tokencorresponds tonext-auth.csrf-tokensession_tokencorresponds to__Secure-next-auth.session-token
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 |
Automatically downgrades to anonymous Auto mode when all tokens are unavailable:
| Option | Description |
|---|---|
fallback_to_auto |
Enable fallback to anonymous mode (default true) |
# 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 }'
| Model ID | Mode | Description |
|---|---|---|
| Search Mode (Pro) | ||
perplexity-search |
pro | Default search model |
sonar-search |
pro | Sonar model |
gpt-5-2-search |
pro | GPT-5.2 |
claude-4-5-sonnet-search |
pro | Claude 4.5 Sonnet |
grok-4-1-search |
pro | Grok 4.1 |
| Reasoning Mode | ||
perplexity-reasoning |
reasoning | Default reasoning model |
gpt-5-2-thinking-reasoning |
reasoning | GPT-5.2 Thinking |
claude-4-5-sonnet-thinking-reasoning |
reasoning | Claude 4.5 Sonnet Thinking |
gemini-3-0-pro-reasoning |
reasoning | Gemini 3.0 Pro |
kimi-k2-thinking-reasoning |
reasoning | Kimi K2 Thinking |
grok-4-1-reasoning-reasoning |
reasoning | Grok 4.1 Reasoning |
| Deep Research Mode | ||
perplexity-deepsearch |
deep research | Deep research model |
- Settings → AI Provider → Add Custom Provider
- Fill in:
- API Host:
http://127.0.0.1:8000 - API Key:
sk-123456
- API Host:
- Select model:
perplexity-searchorperplexity-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