Perplexity Mcp

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](#-features) · [Quick Start](#-quick-start) · [Admin Panel](#%EF%B8%8F-admin-panel) · [Configuration](#%EF%B8%8F-configuration) · [Architecture](#%EF%B8%8F-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.1
• gpt-5.2-thinking · claude-4.5-sonnet-thinking
• gemini-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 Code

claude mcp add perplexity -s user -- uv --directory /path/to/perplexity-mcp run perplexity-mcp

🟢 Cursor

Go to Settings → MCP → Add new server and paste:

{
  "command": "uv",
  "args": ["--directory", "/path/to/perplexity-mcp", "run", "perplexity-mcp"]
}

🔵 Windsurf / VS Code / Other MCP clients

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](#-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.

| Parameter | Type | Default | Description | |:----------|:-----|:--------|:------------| | query | string | required | Natural language question with context | | model | string | null | Model selection (see [models](#-9-models-available)) | | sources | array | ["web"] | Sources: web, scholar, social | | language | string | en-US | ISO 639 language code |

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.

| Parameter | Type | Default | Description | |:----------|:-----|:--------|:------------| | query | string | required | Detailed research question with full context | | sources | array | ["web", "scholar"] | Sources: web, scholar, social | | language | string | en-US | ISO 639 language code |

> [!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/

| Feature | Description | |:--------|:------------| | 📊 Stats Grid | Total clients, Online/Exhausted counts, Monitor status | | 📋 Token Table | Sortable columns, filter pills (Online/Exhausted/Offline/Unknown), icon actions | | 💰 Quota Column | Per-token breakdown — Pro remaining, Research quota, Agentic research | | ❤️ Health Monitor | Zero-cost checks via rate-limit API, configurable interval | | 📱 Telegram Alerts | Notifications on token state changes (expired, exhausted, back online) | | 🔄 Fallback Toggle | Enable/disable automatic Pro → free fallback | | 📥 Import/Export | Bulk token management via JSON config files | | 📝 Log Viewer | Live streaming, level filter (Error/Warning/Info/Debug), search, follow mode | | 🧪 Test Button | Run health check on individual tokens or all at once |

---

🔐 Authentication

By default, the server uses anonymous Perplexity sessions (rate limited). For Pro access, add your session tokens.

How to Get Tokens

1. Sign in at perplexity.ai
2. Open DevTools (F12) → Application → Cookies
3. Copy these two cookies:

• next-auth.csrf-token
• next-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

| Variable | Default | Description | |:---------|:--------|:------------| | PERPLEXITY_TIMEOUT | 900 | Request timeout in seconds (15 min for deep research) | | SOCKS_PROXY | — | SOCKS5 proxy URL (socks5://host:port) |

Token States

Token state is computed automatically from session_valid + rate_limits (never set manually):

| State | Meaning | Badge | Behavior | |:------|:--------|:------|:---------| | 🟢 normal | Session valid, pro quota available | Online | Used for all requests | | 🟡 exhausted | Session valid, pro quota = 0 | Exhausted | Skipped for Pro, used as auto fallback | | 🔴 offline | Session invalid/expired | Offline | Not used for any requests | | 🔵 unknown | Not yet checked | Unknown | Used normally (quota assumed available) |

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/   │   │
│  └─────────────┘                    └────────────────┘   │
└──────────────────────────────────────────────────────────┘

| Component | File | Role | |:----------|:-----|:-----| | MCP Server | src/server.py | Stdio transport, pool state sync, timeout handling | | Tool Definitions | src/tools.py | 2 MCP tools with LLM-optimized descriptions | | API Client | perplexity/client.py | Perplexity API via curl_cffi (bypasses Cloudflare) | | Client Pool | perplexity/server/client_pool.py | Round-robin, backoff, monitor, state persistence | | Query Engine | perplexity/server/app.py | Rotation loop, 3-level fallback, validation | | Admin API | perplexity/server/admin.py | REST endpoints + static file serving | | Admin UI | perplexity/server/web/ | React + Vite + Tailwind dashboard |

---

🧪 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)

---

📄 License

[MIT](LICENSE)

Source & license

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

• Author: teoobarca
• Source: teoobarca/perplexity-mcp
• License: MIT

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