helallao/perplexity-ai

What This Project Does

Perplexity AI is a Python library that lets you query the Perplexity AI search engine programmatically — without using an official API key. It works by reverse-engineering Perplexity's internal web endpoints, and it also includes a browser‑automation tool that can create fresh Gmail accounts via Emailnator to reset the 5 free Pro queries per day.

Think of it as an unofficial, feature‑rich client for Perplexity that supports:

Search modes: auto, pro, reasoning, deep research
Choice of underlying models (e.g., GPT‑5, Claude 4.5, Grok, etc.)
File upload for document Q&A
Streaming responses
Follow‑up questions
Sync & async APIs
A web interface (browser automation) for account generation
An MCP (Model Context Protocol) server so tools like Claude Code can use Perplexity as a search backend

Key Features

Account Generation – Uses Emailnator to create disposable Gmail accounts, which renew the free Pro query limit.
MCP Server – Exposes Perplexity search as tools (perplexity_ask, perplexity_research, etc.) for MCP clients like Claude Code. Works without an API key, using cookies instead.
Flexible Search – Choose modes, models, sources (web/scholar/social), upload files, and stream answers.
Robust Error Handling & Logging – Custom exceptions and structured logging.
Async & Sync APIs – Both perplexity (sync) and perplexity_async modules.
Web Automation – Uses Patchright (undetectable Chrome) to automate account creation and usage in a real browser.

How It Works

The library taps into Perplexity's private web query endpoints. You can either:

Use it anonymously (limited to auto mode), or
Provide your own Perplexity cookies to unlock pro, reasoning, and deep research.

For unlimited Pro queries, the library automatically creates new Gmail addresses via Emailnator, effectively resetting the free tier allowance each time.

The MCP server runs as a separate process (stdio or HTTP) and exposes Perplexity as tools. It keeps a local SQLite journal for long‑running research jobs, with persistent status tracking and graceful failure handling.

Why It’s Notable

It demonstrates how to build a robust client around a hidden API with streaming, file upload, async support, and a full‑blown MCP integration.
The inclusion of a journal‑based research task system shows careful engineering for reliability (background workers, idempotency, queue limits).
It shows how to integrate a third‑party AI service into agent workflows via MCP, a hot topic in 2025.

Caveats

ToS & ethical concerns: The account‑generation feature likely violates Perplexity’s Terms of Servicefull-loop "unlimited pro queries”\ by creating disposable accounts. Use at your own risk.
No official API key required – but the approach relies on scraping endpoints that could change at any time.
Windows limitations – The research journal MCP tools are only supported on POSIX systems due to file‑permission constraints.

In short: a clever, well‑engineered unofficial client that pushes the boundaries of what you can do with a web service without an official API.