Provides tools for searching Perplexity.ai and retrieving answers with cited sources, including support for standard and advanced searches that can filter by web, academic, or social sources.
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-web-mcp Search for recent breakthroughs in fusion energy research"
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.
A lightweight MCP (Model Context Protocol) server that enables AI assistants to perform searches on Perplexity.ai through browser automation. No official API key required.
perplexity-web-mcp bridges your AI assistant (Claude, Cursor, etc.) with Perplexity.ai by automating a real browser session via Playwright. It reads search results directly from the DOM — making it indistinguishable from a real user — and returns the answer text along with cited sources.
Login once, search forever — use the login tool to authenticate once; your session persists across restarts
Lazy browser launch — the browser only opens on the first tool call, not at server startup
Always visible browser — runs non-headless to bypass Cloudflare's bot detection (the window stays in the background during searches)
Sources included — returns cited URLs alongside the answer text
Zero API key — uses your existing Perplexity session (free or Pro)
Related MCP server: Perplexity MCP Server
Prerequisites:
Node.js >= 20
Chromium (via Playwright): npx playwright install chromium
npx playwright install chromiumThat's it — no clone, no build required.
claude mcp add perplexity-web -- npx perplexity-web-mcp@latestAdd to your MCP config (.claude.json):
{
"mcpServers": {
"perplexity-web": {
"command": "npx",
"args": ["perplexity-web-mcp@latest"]
}
}
}Optional flag: --timeout=N — max seconds to wait for an answer (default: 20).
To authenticate, ask your AI client to call the login tool once. A Chromium window will open for you to sign in. Your session is persisted in .playwright/profile/ and reused on future runs.
Why is a browser window visible? Perplexity.ai uses Cloudflare Turnstile which blocks headless browsers. The window stays in the background and requires no interaction during normal use.
loginChecks if you are authenticated on Perplexity.ai. If not, opens a browser window so you can log in.
Parameters: none
Returns: A status message — either "Already authenticated" or "Login successful" after the user completes the login flow.
Your session is persisted in
.playwright/profile/— you only need to callloginonce, or after a session expiry.
searchPerforms a search on Perplexity.ai using default settings and returns the answer with sources. Prefer this for general queries.
Parameters:
Name | Type | Required | Description |
|
| Yes | The search query |
Returns:
The capital of France is Paris...
Sources:
1. [Capital City of France - CountryReports](https://www.countryreports.org/...)search_advancedSame as search but lets you select which sources Perplexity searches. You can combine multiple sources. Uses browser UI automation to toggle the source checkboxes — more powerful but slightly less resilient to UI changes.
Parameters:
Name | Type | Required | Description |
|
| Yes | The search query |
|
| Yes | One or more sources: |
Example: sources: ["web", "academic"] searches both general web and scholarly articles simultaneously.
Returns: Same format as search.
┌─────────────────────────────────────────────────────────────────┐
│ AI Client (Claude Desktop / Claude Code / Cursor / ...) │
└────────────────────────┬────────────────────────────────────────┘
│ MCP stdio transport
▼
┌─────────────────────────────────────────────────────────────────┐
│ perplexity-web-mcp (FastMCP server) │
│ │
│ ┌─────────────────┐ ┌──────────────────────────────────────┐ │
│ │ CLI Arguments │ │ MCP Tools │ │
│ │ │ │ │ │
│ │ --timeout=N │ │ login() │ │
│ │ │ │ checks session, opens browser │ │
│ │ │ │ for login if not authenticated │ │
│ │ │ │ │ │
│ │ │ │ search(query, mode?) │ │
│ │ │ │ returns: { answer, sources[] } │ │
│ └────────┬────────┘ └──────────────┬───────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Browser Manager (Playwright, always visible) │ │
│ │ │ │
│ │ (browser launches lazily on first tool call) │ │
│ │ │ │
│ │ login() │ │
│ │ ├── GET /api/auth/session │ │
│ │ │ ├── active ──► "already authenticated" │ │
│ │ │ └── none ──► open browser, wait for user login │ │
│ │ │ │
│ │ search(query) │ │
│ │ ├── open new tab, navigate to perplexity.ai │ │
│ │ ├── type query in search box │ │
│ │ ├── wait for answer to complete (DOM signal) │ │
│ │ ├── extract answer text from DOM │ │
│ │ ├── extract cited sources │ │
│ │ └── close tab │ │
│ │ │ │
│ │ search_advanced(query, sources[]) │ │
│ │ ├── open new tab, navigate to perplexity.ai │ │
│ │ ├── open "+" menu → "Connecteurs et sources" │ │
│ │ ├── toggle source checkboxes to match requested sources │ │
│ │ ├── type query, wait for answer, extract DOM │ │
│ │ └── close tab │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────┐
│ perplexity.ai │
│ (real browser req) │
└──────────────────────┘# Run in development mode (hot reload)
npm run dev
# Build
npm run build
# Lint
npm run lint
# Type check
npm run typecheckSee docs/testing.md for a full step-by-step guide covering:
First-time authentication flow
Persistent session verification
Integration with Claude Code / Claude Desktop
Lazy browser launch — the browser only opens when the first tool (login or search) is called, not at server startup.
Login — the login tool calls GET /api/auth/session to check the persisted session. If no session is found, a browser window opens and the server waits for the user to log in (up to 5 minutes).
Search — the search tool opens a new tab, navigates to perplexity.ai, types the query, and waits for Perplexity's answer to complete (detected via a DOM signal — the "N sources" button appearing).
Search Advanced — search_advanced does the same but first opens the source selector menu and toggles the requested sources (identified by their SVG icon IDs, which are locale-independent).
Extraction — the answer and sources are extracted from the DOM and returned as text to the MCP client. The tab is then closed.
Visible browser — the browser always runs non-headless to pass Cloudflare's Turnstile bot detection, which reliably blocks headless Chromium regardless of stealth patches.
Depends on Perplexity.ai's DOM structure — may break if they update their UI
Rate limiting applies as per Perplexity's standard usage policies
A visible browser window is always present (required to bypass Cloudflare Turnstile)
Pro features (deeper research, Claude model) require an authenticated Pro account
Contributions are welcome! Please open an issue before submitting large PRs.
Fork the repo
Create a branch: git checkout -b feat/my-feature
Commit your changes
Open a Pull Request
MIT — see LICENSE for details.
This project automates a browser session for personal use. It is not affiliated with Perplexity AI, Inc. Use responsibly and in accordance with Perplexity's Terms of Service.
Check if you are authenticated on Perplexity.ai. If not, opens a browser window so you can log in.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors (authentication check, browser opening) without annotations, but could detail post-login behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no wasted words, efficiently conveying purpose and action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core functionality well; lacks detail on return value or post-login state, but adequate for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline 4 applies; description adds no parameter info but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool checks authentication and optionally opens a browser for login, distinguishing it from sibling search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (to check/login) and what happens next, though no explicit when-not or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the web using Perplexity.ai and get an AI-synthesized answer with cited sources. Uses default Perplexity settings.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses that it uses default Perplexity settings and returns a synthesized answer with sources, but it does not mention potential rate limits, authentication needs, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence front-loads the purpose and result, and the second adds relevant context about default settings. It is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is fairly complete. It explains what the tool does and mentions the default setting context. However, it could mention any output format or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description does not add any additional meaning to the 'query' parameter beyond what the schema already provides, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches the web using Perplexity.ai and returns an AI-synthesized answer with cited sources. It distinguishes itself from the sibling 'login' but does not explicitly differentiate from 'search_advanced', though mentioning 'default settings' hints at a distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that normal searches use defaults, but it doesn't explicitly state when to use this tool versus 'search_advanced' or provide any prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Perplexity.ai with specific source selection. Lets you combine multiple sources (e.g. web + academic). Use this when source control matters; prefer search for general queries.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query | |
| sources | Yes | Sources to search: 'web' (general web), 'academic' (scholarly articles), 'social' (Reddit & forums). Can combine multiple. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly describes the operation as a search, implying non-destructive behavior. While it doesn't detail auth, rate limits, or output format, the core behavior is transparent. A small deduction for missing details that could be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load purpose and usage guidelines. Every sentence adds value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (two required parameters, no output schema, no nested objects), the description adequately covers its function and when to use it. It is complete for an AI agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have schema descriptions, providing 100% coverage. The description reinforces the ability to combine sources (e.g., web + academic), which adds some context but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches Perplexity.ai with specific source selection, and distinguishes from the sibling 'search' tool by noting that 'search' is preferred for general queries. This provides a specific verb-resource pair with differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool ('when source control matters') and when not to ('prefer `search` for general queries'), along with an example of combining sources. This is excellent guidance for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.1loginsearchsearch_advancedScored across 3 tools
Each tool has a clearly distinct purpose: search is for general queries, search_advanced provides explicit source control, and login handles authentication. There is no ambiguity between them.
search and search_advanced follow a consistent lowercase snake_case pattern, though login deviates from the 'search' prefix. The naming is still clear and predictable overall.
With only 3 tools, the set is minimal yet complete for its purpose—performing web searches and handling authentication. Each tool earns its place without bloat or redundancy.
The surface covers the full search lifecycle: a standard search, an advanced search with source selection, and an auth check to ensure access. No significant gaps are apparent for a web search MCP.
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.
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
