perplexity-mcp
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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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
Related MCP server: Perplexity Web-Search MCP
โจ 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.json53 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 sync2. Add to Your AI Tool
claude mcp add perplexity -s user -- uv --directory /path/to/perplexity-mcp run perplexity-mcpGo 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 |
| string | required | Natural language question with context |
| string |
| Model selection (see models) |
| array |
| Sources: |
| string |
| 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-detectedperplexity_research
Deep research agent for comprehensive analysis. Returns extensive reports with 10-30+ citations.
Parameter | Type | Default | Description |
| string | required | Detailed research question with full context |
| array |
| Sources: |
| string |
| ISO 639 language code |
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-serverOpens 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-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": "..." }
]
}Session tokens last ~30 days. The monitor detects expired tokens and alerts you via Telegram.
โ๏ธ Configuration
Environment Variables
Variable | Default | Description |
|
| Request timeout in seconds (15 min for deep research) |
| โ | SOCKS5 proxy URL ( |
Token States
Token state is computed automatically from session_valid + rate_limits (never set manually):
State | Meaning | Badge | Behavior |
๐ข | Session valid, pro quota available | Online | Used for all requests |
๐ก | Session valid, pro quota = 0 | Exhausted | Skipped for Pro, used as auto fallback |
๐ด | Session invalid/expired | Offline | Not used for any requests |
๐ต | 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 |
| Stdio transport, pool state sync, timeout handling |
Tool Definitions |
| 2 MCP tools with LLM-optimized descriptions |
API Client |
| Perplexity API via curl_cffi (bypasses Cloudflare) |
Client Pool |
| Round-robin, backoff, monitor, state persistence |
Query Engine |
| Rotation loop, 3-level fallback, validation |
Admin API |
| REST endpoints + static file serving |
Admin UI |
| 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 buildProject 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
Available Tools
2 toolsperplexity_askB
AI-powered answer engine for tech questions, documentation lookups, and how-to guides. Perplexity is an AI model (not a search engine) - provide context and specific requirements in your query for better results. Returns synthesized answers with citations.
Inputs: query (required), sources, language.
perplexity_researchA
Deep research agent for comprehensive analysis of complex topics. Provide detailed context about what you need and why - this AI model spends more time gathering and synthesizing information. Returns extensive reports with 10-30+ citations. Use for architecture decisions, technology comparisons, or thorough investigations.
Inputs: query (required), sources, language.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one for quick answers and tech lookups, the other for deep research with extensive citations. There is no overlap in functionality.
Both tools follow a consistent pattern with the 'perplexity_' prefix and a descriptive verb ('ask', 'research'), making it easy to understand their purpose.
With only two tools, the server covers the core use cases of quick queries and deep research. While minimal, it is well-scoped and not overly sparse for its intended purpose.
The tool set covers the primary interactions with the Perplexity AI model: quick synthesis and comprehensive analysis. There are no major gaps, though additional tools for streaming or specific models could be considered.
Maintenance
Related MCP Connectors
Real-time web search, reasoning, and research through Perplexity's API
Enable AI assistants to perform web searches using Perplexity's Sonar Pro.
Web search, browser automation, scraping, crawling and CAPTCHA solving for AI agents.
Web scraping, search, crawling, structured extraction and research for AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides AI assistants with real-time web search, reasoning, and research capabilities through Perplexity's Sonar models and Search API. Supports quick searches, deep research, advanced reasoning, and direct web search with ranked results.475,070 npm2,639MIT
- FlicenseBqualityDmaintenanceEnables AI assistants to perform real-time web and academic searches using Perplexity's Sonar API.2-
- AlicenseAqualityDmaintenanceProvides AI-powered research capabilities through Perplexity's web interface, enabling web search, deep research, chat, and documentation retrieval without API keys.8GPL 3.0
- FlicenseNot gradedqualityDmaintenanceGives AI agents live research and image generation capabilities by automating a logged-in Perplexity Pro browser session.-