helallao/perplexity-ai: an unofficial Perplexity client that generates its own accounts

What helallao/perplexity-ai actually solves

Perplexity's own API needs a paid key. This project takes the other route: it talks to the perplexity.ai web interface directly, so a script can ask questions without a billing relationship. The README states the goal plainly, calling it a Python module that "leverages Emailnator to generate new accounts for unlimited pro queries". That is the pitch, and it is also the design constraint. The package is for developers who want programmatic answers in Python and are willing to depend on an interface that was not built for them. It is not a hosted service and it is not affiliated with Perplexity. The repository carries the MIT licence, Python 3.10 or newer, and a version number of 0.2.0 with a Beta development status classifier in pyproject.toml. The last push to the default branch was on 2026-09-08, so the code is recent, but the README does not describe a release process or a support commitment.

How the wrapper, the async client and the MCP server fit together

The repository ships three importable pieces. The perplexity package is the synchronous client, perplexity_async is the asyncio equivalent, and perplexity.mcp is the entry point behind the perplexity-mcp command declared under [project.scripts]. Both clients expose a search method that returns a dictionary with an answer key, and both accept a cookies dictionary to move from anonymous access to the pro, reasoning and deep research modes. Under the hood the declared dependencies are curl_cffi and websocket-client, which tells you the transport is HTTP plus a websocket for streaming rather than a vendor SDK. The MCP server reuses the same reverse-engineered path, and it is the one component with a documented feature gap: the README's comparison table lists messages array input, search_recency_filter, search_domain_filter, search_context_size, reasoning_effort, strip_thinking and structured search results as present in the official @perplexity-ai/mcp-server and absent here. The server answers with plain text only. That table is the most honest part of the documentation, and it is worth reading before you plan around the tool.

Installing helallao/perplexity-ai and running a first query

The README assumes uv. For a plain library install, uv sync creates the environment from uv.lock. The README notes that pip users can substitute pip install -e . for uv sync and call tools directly instead of through uv run.

uv sync

The optional extras are separate. The driver extra pulls patchright and playwright for the browser-based web interface, and the README adds a second step to fetch the Chromium build. The mcp extra is what you need for the MCP server.

uv sync --extra driver
uv run patchright install chromium
uv sync --extra mcp

With the library in place, the README's basic example is three lines. It constructs a client with no arguments and prints the answer field of the returned dictionary. Anonymous use is limited to auto mode, according to the same section.

import perplexity

client = perplexity.Client()
response = client.search("What is artificial intelligence?")
print(response['answer'])

To reach the higher modes you pass cookies. The README shows a dictionary with next-auth.csrf-token and next-auth.session-token, and a call that sets mode to pro, model to gpt-5.2 and sources to a list containing scholar. It points to a "How To Get Cookies" section for the extraction steps, which is where you should look before assuming the values are easy to obtain.

cookies = {
    'next-auth.csrf-token': 'your-token',
    'next-auth.session-token': 'your-session',
}

client = perplexity.Client(cookies)
response = client.search("Complex query here", mode='pro', model='gpt-5.2', sources=['scholar'])

The MCP server, and why it is the most reusable part

For Claude Code users the MCP path is the least invasive way to try this project. Install the extra, then register the stdio server with one command. The client spawns the process itself, so there is no port to manage.

uv sync --extra mcp
claude mcp add perplexity -- perplexity-mcp

The server exposes four tools, each mapped to a Perplexity mode: perplexity_ask to auto, perplexity_research to deep research, perplexity_reason to reasoning, and perplexity_search to pro with web sources. Without the PERPLEXITY_COOKIES environment variable the server runs anonymously and only auto mode is reachable, which means perplexity_research, perplexity_reason and perplexity_search are effectively out of reach until you supply cookies. The README documents an alternative HTTP transport selected through MCP_TRANSPORT, defaulting to stdio, with MCP_HOST and MCP_PORT for binding and an endpoint at http://<host>:<port>/mcp. The HTTP mode is the one to pick if several machines should share a single server.

MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=9000 perplexity-mcp

Where this project breaks, and who should avoid it

Everything here rests on an interface Perplexity did not publish. The README says the MCP server "works without an API key by using the same reverse-engineered web interface as the rest of this library". That sentence is the risk statement. When Perplexity changes its front end, the wrapper has no contract to fall back on, and the fix is a new commit rather than a version bump you can pin. The second dependency is Emailnator. Account generation is not a convenience layer bolted on the side; it is the mechanism behind "unlimited pro queries", so the project inherits Emailnator's availability and whatever terms govern it. Nothing in the README describes a fallback when either side changes, and there is no retrieved release history to suggest a cadence of fixes. The MCP comparison table also rules out structured citations and images, so a workflow that needs to cite sources cannot be built on this server. Finally, the account generation angle is the kind of thing that draws scrutiny from the service being automated. The repository has a SECURITY.md at the top level, but the README excerpt does not describe what it covers; treat that file as required reading rather than an afterthought.

The official Perplexity MCP server is the honest alternative

The README compares itself to @perplexity-ai/mcp-server, and the difference is a straight trade. The official server requires a paid Perplexity API key. This one does not. In exchange you give up the messages array input, the recency and domain filters, the context-size control, reasoning_effort, strip_thinking, and structured search results with citations and images. So the choice is not about which server is better built. It is about whether you are paying for a supported API surface or accepting a plain-text answer from an interface that can change without notice. If your agent needs to filter by domain or return citations, the official server is the only one of the two that does it. If you are experimenting and an API key is not in the budget, this project is the one that runs. The same logic applies outside MCP: any client built on Perplexity's documented API will be more predictable than a wrapper built on its website.

Licence, maintenance and the cost of upgrading

The licence is MIT, declared both in the README badge and in the license field of pyproject.toml. MIT is permissive, so the usual obligations are attribution and keeping the notice, but this is not legal advice and the repository's own LICENSE file is the text that governs. Two details in pyproject.toml deserve a second look. The project name is perplexity-api while the repository is helallao/perplexity-ai, so the installable name and the repo name diverge. The author email is [email protected], which is a perplexity.ai address rather than the repository owner's, and the project URLs point at github.com/ESousa97/perplexity-ai rather than the repository you are reading. None of that is a licence problem, but it does mean you should confirm which source tree you are actually installing from. On upgrades, the version is 0.2.0 and the classifier is Beta. Because the dependency is a web interface rather than a versioned API, an upgrade is not a matter of reading a changelog and bumping a pin; the docs directory lists a CHANGELOG and an IMPROVEMENTS file, and those are where the project records what moved. Budget for re-testing your queries after any upstream change, and expect the failure to appear at runtime rather than at install time.

Editorial conclusion

Adopt it for prototyping, personal scripts and MCP experiments where the free auto mode is enough and you can tolerate breakage. Do not adopt it for production workloads, commercial products or anything that needs a support contract, because it depends on reverse-engineered endpoints and an Emailnator account generator. Before you commit, read SECURITY.md, check whether the MIT licence in pyproject.toml is the one you are relying on, and test whether anonymous auto mode answers your queries without cookies.

Frequently asked questions

Official sources

1. helallao/perplexity-ai on GitHub
2. Issues
3. License: MIT
4. Project website
5. README