The only Perplexity MCP server with multi-account pooling, an admin dashboard, and zero-cost monitoring. No API keys. No per-query fees. Uses your existing Perplexity Pro session.
Features · Quick Start · Admin Panel · Configuration · Architecture
🎯 Why This One?
Most Perplexity MCP servers are single-account wrappers around the paid Sonar API. This one is different:
- 🆓 No API costs — uses session cookies, not the paid API. Same features, zero per-query fees
- 🏊 Multi-account pool — round-robin across N accounts with automatic failover
- 📊 Admin dashboard — React UI to monitor quotas, manage tokens, tail logs in real-time
- ❤️ Zero-cost health checks — monitors all accounts via rate-limit API without consuming queries
- 🛡️ Downgrade protection — detects when Perplexity silently returns a regular result instead of deep research
- 📱 Telegram alerts — get notified when tokens expire or quota runs out
✨ Features
🔍 Smart Search
- Pro Search — fast, accurate answers with citations
- Reasoning — multi-model thinking for complex decisions
- Deep Research — comprehensive 10-30+ citation reports
- Multi-source — web, scholar, and social
🤖 9 Models Available
sonar·gpt-5.2·claude-4.5-sonnet·grok-4.1gpt-5.2-thinking·claude-4.5-sonnet-thinkinggemini-3.0-pro·kimi-k2-thinking·grok-4.1-reasoning
🏊 Token Pool Engine
- Round-robin rotation across accounts
- Exponential backoff on failures (60s → 120s → ... → 1h cap)
- 3-level fallback — Pro → auto (exhausted) → anonymous
- Smart quota tracking — decrements locally, verifies at zero
- Hot-reload — add/remove tokens without restart
🛡️ Production Hardened
- Silent deep research downgrade detection
- Atomic config saves (no corruption on crash)
- Connection drop handling
- Cross-process state sharing via
pool_state.json - 53 unit tests
🖼️ Screenshots
Token Pool Dashboard
Stats grid, monitor controls, sortable token table with per-account quotas (Pro / Research / Agentic), filter pills, and one-click actions.
Log Viewer
Live log streaming with auto-refresh, level filtering, search highlighting, follow mode, and line numbers.
🚀 Quick Start
1. Clone & Install
git clone https://github.com/teoobarca/perplexity-mcp.git
cd perplexity-mcp
uv sync
2. Add to Your AI Tool
claude mcp add perplexity -s user -- uv --directory /path/to/perplexity-mcp run perplexity-mcp
Go to Settings → MCP → Add new server and paste:
{
"command": "uv",
"args": ["--directory", "/path/to/perplexity-mcp", "run", "perplexity-mcp"]
}
Add to your MCP config file:
{
"mcpServers": {
"perplexity": {
"command": "uv",
"args": ["--directory", "/path/to/perplexity-mcp", "run", "perplexity-mcp"]
}
}
}
That's it. Works immediately with anonymous sessions. Add your tokens for Pro access — see Authentication.
🛠️ Tools
Two MCP tools with LLM-optimized descriptions so your AI assistant picks the right one automatically:
perplexity_ask
AI-powered answer engine for tech questions, documentation lookups, and how-to guides.
Mode auto-detection: Models with thinking or reasoning in the name automatically switch to Reasoning mode.
"gpt-5.2" → Pro Search
"gpt-5.2-thinking" → Reasoning Mode ← auto-detected
perplexity_research
Deep research agent for comprehensive analysis. Returns extensive reports with 10-30+ citations.
[!TIP] Deep research takes 2-5 minutes per query. Provide detailed context and constraints for better results. The server has a 15-minute timeout to accommodate this.
🖥️ Admin Panel
A built-in web dashboard for managing your token pool. Start it with:
perplexity-server
Opens automatically at http://localhost:8123/admin/
🔐 Authentication
By default, the server uses anonymous Perplexity sessions (rate limited). For Pro access, add your session tokens.
How to Get Tokens
- Sign in at perplexity.ai
- Open DevTools (F12) → Application → Cookies
- Copy these two cookies:
next-auth.csrf-tokennext-auth.session-token
Single Token
Create token_pool_config.json in the project root:
{
"tokens": [
{
"id": "my-account",
"csrf_token": "your-csrf-token-here",
"session_token": "your-session-token-here"
}
]
}
Multi-Token Pool
Add multiple accounts for round-robin rotation with automatic failover:
{
"monitor": {
"enable": true,
"interval": 6,
"tg_bot_token": "optional-telegram-bot-token",
"tg_chat_id": "optional-chat-id"
},
"fallback": {
"fallback_to_auto": true
},
"tokens": [
{ "id": "account-1", "csrf_token": "...", "session_token": "..." },
{ "id": "account-2", "csrf_token": "...", "session_token": "..." },
{ "id": "account-3", "csrf_token": "...", "session_token": "..." }
]
}
[!NOTE] Session tokens last ~30 days. The monitor detects expired tokens and alerts you via Telegram.
⚙️ Configuration
Environment Variables
Token States
Token state is computed automatically from session_valid + rate_limits (never set manually):
Fallback Chain
When a Pro request fails, the server tries progressively:
1. ✅ Next client with Pro quota (round-robin)
2. ✅ Next client with Pro quota ...
3. 🟡 Any available client (auto mode)
4. 🔵 Anonymous session (auto mode)
5. ❌ Error returned to caller
🏗️ Architecture
┌─────────────────────────────────────────────────────────┐
│ Your AI Assistant (Claude Code / Cursor / Windsurf) │
└──────────────────────┬──────────────────────────────────┘
│ MCP (stdio)
▼
┌──────────────────────────────────────────────────────────┐
│ perplexity-mcp │
│ ┌────────────────┐ ┌────────────────────────────────┐ │
│ │ tools.py │ │ server.py │ │
│ │ • ask │──│ • Pool state sync │ │
│ │ • research │ │ • Timeout handling │ │
│ └────────────────┘ └────────────────────────────────┘ │
└──────────────────────┬───────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ Backend Engine (perplexity/) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ client.py │ │ client_pool │ │ admin.py │ │
│ │ • Search │ │ • Rotation │ │ • REST API │ │
│ │ • Upload │ │ • Backoff │ │ • Static │ │
│ │ • Validate │ │ • Monitor │ │ files │ │
│ └──────┬───────┘ │ • Fallback │ └────────┬───────┘ │
│ │ └──────────────┘ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌────────────────┐ │
│ │ Perplexity │ │ React Admin UI │ │
│ │ (web API) │ │ :8123/admin/ │ │
│ └─────────────┘ └────────────────┘ │
└──────────────────────────────────────────────────────────┘
🧪 Development
# Install in development mode
uv pip install -e ".[dev]" --python .venv/bin/python
# Run unit tests (53 tests)
.venv/bin/python -m pytest tests/ -v
# Frontend development
cd perplexity/server/web
npm install
npm run dev # Dev server with proxy to :8123
npm run build # Production build
Project Structure
src/ # MCP stdio server (thin wrapper)
server.py # Entry point, pool state sync
tools.py # Tool definitions
perplexity/ # Backend engine
client.py # Perplexity API client (curl_cffi)
config.py # Constants, endpoints, model mappings
exceptions.py # Custom exception hierarchy
logger.py # Centralized logging
server/
app.py # Starlette app, query engine
client_pool.py # ClientPool, rotation, monitor
admin.py # Admin REST API
utils.py # Validation helpers
main.py # HTTP server entry point
web/ # React admin frontend (Vite + Tailwind)
tests/ # 53 unit tests
⚠️ Limitations
- Unofficial — uses Perplexity's web interface, may break if they change it
- Cookie-based auth — session tokens expire after ~30 days
- Rate limits — anonymous sessions have strict query limits
- Deep research — takes 2-5 minutes per query (this is normal)
