Which integrations are available for this server?

Provides tools for AI-powered search and deep research using Perplexity's Pro Search, Reasoning, and Deep Research capabilities with multi-account pooling, automatic failover, and zero-cost health monitoring.

How do I use perplexity-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@perplexity-mcp research the benefits of intermittent fasting" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

perplexity-mcp by teoobarca

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.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 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.

Parameter	Type	Default	Description
`query`	string	required	Natural language question with context
`model`	string	`null`	Model selection (see models)
`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

Sign in at perplexity.ai
Open DevTools (F12) → Application → Cookies
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

perplexity-mcp

🎯 Why This One?

✨ Features

🔍 Smart Search

🤖 9 Models Available

🏊 Token Pool Engine

🛡️ Production Hardened

🖼️ Screenshots

Token Pool Dashboard

Log Viewer

🚀 Quick Start

1. Clone & Install

2. Add to Your AI Tool

🛠️ Tools

`perplexity_ask`

`perplexity_research`

🖥️ Admin Panel

🔐 Authentication

How to Get Tokens

Single Token

Multi-Token Pool

⚙️ Configuration

Environment Variables

Token States

Fallback Chain

🏗️ Architecture

🧪 Development

Project Structure

⚠️ Limitations

📄 License

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API