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

Overview Schema Related Servers Score Discussions

Python

Remote

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

Available Tools

2 tools

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

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Natural language question with context. Include specific requirements, constraints, or use case. Example: 'How to implement JWT auth in Next.js 14 App Router with httpOnly cookies for a SaaS app?'
`sources`	No	Information sources to search. Default: ['web']
`language`	No	ISO 639 language code. Default: 'en-US'

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It notes that Perplexity is an AI model (not a search engine) and returns synthesized answers with citations. It does not mention potential limitations, auth needs, or rate limits, leaving gaps in behavioral understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences. The first sentence states the purpose, and the second provides guidance and output expectations. It is efficiently structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the basic purpose and output (citations) but lacks details like default sources, limitations, or comparison with the sibling tool. It is adequate for a simple Q&A tool but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds a usage tip for the query parameter (provide context) but does not add significant meaning beyond the schema for the other parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: an AI-powered answer engine for tech questions, documentation lookups, and how-to guides. It distinguishes from a search engine but does not differentiate from its sibling tool perplexity_research.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It advises providing context and specific requirements for better results, implying usage scenarios. However, it does not explicitly state when to use this tool vs. its sibling, nor does it mention when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Detailed research question with full context. Explain the problem, constraints, and what insights you need. Example: 'Best practices for LLM API key rotation in production Node.js apps - need patterns for zero-downtime rotation, secret storage options, and monitoring.'
`sources`	No	Information sources. Default: ['web', 'scholar']
`language`	No	ISO 639 language code. Default: 'en-US'

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses extensive research behavior and citation count, but omits potential downsides like cost, latency, or rate limits. Adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise paragraphs, front-loaded with purpose. Each sentence adds value; no wordiness. Slightly longer than necessary but still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description covers return type (extensive reports with citations) and parameter usage. Might benefit from output format details, but overall sufficient for a research tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and description adds valuable context for the 'query' parameter with an example and guidance on detail level. Sources and language are adequately described in schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a 'deep research agent' for comprehensive analysis, distinguishing it from the sibling 'perplexity_ask' by emphasizing deeper synthesis, more time, and extensive citations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states use cases like architecture decisions and technology comparisons, and guides on providing detailed context. Lacks explicit 'when not to use' but context implies lighter queries belong to sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

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.

Naming Consistency5/5

Both tools follow a consistent pattern with the 'perplexity_' prefix and a descriptive verb ('ask', 'research'), making it easy to understand their purpose.

Tool Count4/5

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.

Completeness4/5

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

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Perplexity API Platform
io.github.perplexityai
Real-time web search, reasoning, and research through Perplexity's API
Search Browser Automation RAG Systems
2
arjunkmrm-perplexity-search AOAuth
ai.smithery
Enable AI assistants to perform web searches using Perplexity's Sonar Pro.
Search Browser Automation
3
seltz-ai-seltz-mcp
ai.seltz
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Search Browser Automation Web Scraping
2
caesar A
com.trycaesar
Web search and page-reading for AI agents. One-click OAuth connect, or a Caesar API key.
Search Browser Automation
2

Related MCP Servers

Perplexity API Platform MCP
Search RAG Systems Research & Data
perplexityai
A
license
A
quality
B
maintenance
Provides 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.
Updated 8 days ago (2026-08-27 03:42 UTC)
4
44,116
2,489
MIT
Perplexity Web-Search MCP
Search Research & Data
lv042
F
license
B
quality
C
maintenance
Enables AI assistants to perform real-time web and academic searches using Perplexity's Sonar API.
Updated a year ago (2025-09-17 19:00 UTC)
2
perplexity-mcp
Search AI & Machine Learning
0xHumban
A
license
A
quality
D
maintenance
Enables AI assistants to perform web searches and retrieve real-time information using Perplexity AI's Sonar models, with support for multiple search modes and easy integration with MCP clients.
Updated 10 months ago (2025-10-26 12:06 UTC)
5
1
MIT
Pepe-MCP-Server
Search Browser Automation
AldereteSergio
A
license
A
quality
C
maintenance
Provides AI-powered research capabilities through Perplexity's web interface, enabling web search, deep research, chat, and documentation retrieval without API keys.
Updated 2 months ago (2026-06-26 02:56 UTC)
8
GPL 3.0

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/teoobarca/perplexity-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

🎯 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

Available Tools

TDQS

TDQS

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Perplexity API Platform MCP

Perplexity Web-Search MCP

perplexity-mcp

Pepe-MCP-Server

Latest Blog Posts

MCP directory API

`perplexity_ask`

`perplexity_research`