helallao/perplexity-ai: An Unofficial Perplexity.ai Wrapper With Account Generation and an MCP Server

The problem helallao/perplexity-ai solves

Perplexity.ai's official MCP server, @perplexity-ai/mcp-server, requires a paid Perplexity API key. This project takes the opposite route: it drives the same web interface a browser would use, so a client can ask questions without an API key at all. The README states the server "works without an API key by using the same reverse-engineered web interface as the rest of this library." That is the whole pitch, and it defines the audience.

The second half of the project is account generation. The README says it uses Emailnator to "generate new accounts for unlimited pro queries," framing repeated account creation as a way around query limits. That is a different use case from the MCP server, and a more contentious one, because it depends on a third-party disposable-email service and on Perplexity's signup flow staying automatable.

So the project serves two groups: Python developers who want a Perplexity client with sync and async APIs, and MCP users who want Perplexity search inside Claude Code or Claude Desktop without a key. It is not a general-purpose Perplexity SDK, and the README never claims to be one.

How the client and MCP server actually work

The dependency list is the clearest signal of the mechanism. pyproject.toml requires curl_cffi and websocket-client. curl_cffi impersonates browser TLS fingerprints, which is what lets requests to the web interface look like they come from Chrome rather than from a Python HTTP client. websocket-client handles the streaming path, which matches the streaming example in the README.

The optional driver extra adds patchright and playwright, and the installation section pairs that with patchright install chromium. Patchright is a patched Playwright build; the README links to its "best practices" page and mentions Chrome User Data Directory. That is the browser automation layer behind the web interface, and it is only installed when you ask for it.

The MCP server is a separate entry point. pyproject.toml declares perplexity-mcp = "perplexity.mcp:main" under [project.scripts], and the mcp extra pulls in mcp>=1.0.0. It supports two transports selected by MCP_TRANSPORT, defaulting to stdio. In stdio mode the MCP client spawns the process; in HTTP mode it runs a persistent server, defaulting to 127.0.0.1:8000 with the endpoint at /mcp.

The tools map to Perplexity modes: perplexity_ask for auto, perplexity_research for deep research, perplexity_reason for reasoning, and perplexity_search for pro plus web sources. Authentication is a cookie JSON string in PERPLEXITY_COOKIES. The README is explicit that without it the server "runs anonymously with access to free (auto mode) queries only," and that setting it enables pro, reasoning, and deep research.

Installing helallao/perplexity-ai and running a first query

The README uses uv throughout and notes that pip users can substitute pip install -e . for uv sync. The basic install pulls only the core client dependencies.

uv sync

After that, the README's basic usage example is three lines: construct a perplexity.Client(), call search with a question, and read response['answer']. The response is a dictionary, and the answer text lives under the 'answer' key.

import perplexity

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

For the enhanced modes you pass a cookies dictionary to the constructor and then name a mode, a model and sources on the call. The README's example uses mode='pro', model='gpt-5.2' and sources=['scholar'].

import perplexity

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']
)

If you want the MCP server instead, install the extra and register it with Claude Code. The README shows this exact pair of commands.

uv tool install '.[mcp]'
claude mcp add perplexity -- perplexity-mcp

Running claude mcp list should then show the perplexity entry. The README's manual JSON config uses the same command name and optionally passes PERPLEXITY_COOKIES as a JSON string. For a networked setup, set MCP_TRANSPORT=http and override MCP_HOST and MCP_PORT; the README's example binds 0.0.0.0:9000 and adds the server with claude mcp add --transport http perplexity http://127.0.0.1:8000/mcp.

What the MCP server gives up compared with the official one

The README includes a comparison table against the official @perplexity-ai/mcp-server, and it is unusually candid. The one advantage listed for this project is "No API key required." Everything else in the table is a feature the official server has and this one does not: a messages array input, search_recency_filter, search_domain_filter, search_context_size, reasoning_effort, strip_thinking, and structured search results with citations and images.

That last row matters most. This server returns a plain text answer only. If your workflow needs to render citations, link back to sources, or post-process images, the unofficial server will not supply them, and the official server is the correct choice despite the key requirement. The input shape is also narrower: a single query string rather than a message array, so multi-turn conversation state has to live in your own application.

I would treat the filter parameters as the second real loss. Recency and domain filters are common requirements for research tooling, and the README states plainly that they are not supported here. Anyone building a retrieval pipeline on top of this should read that table before writing integration code.

Account generation, Emailnator, and why the limit-bypass framing is a liability

The account generator is the part I would be most careful about. The README describes generating Gmail accounts through Emailnator to get "unlimited pro queries" by creating new accounts, and the web interface automates the same flow in a browser. Functionally, this means the project's pro-mode story depends on a third party (Emailnator) and on Perplexity's signup flow remaining scriptable.

Neither dependency is under the project's control. If Emailnator changes its interface, or if signup adds a check that patchright cannot pass, the generator stops working and the pro path degrades. The README does not document a fallback for that case. The cookie-based path is the more durable one: supply your own next-auth.session-token and the client uses your existing session rather than creating one.

There is also a licensing and terms question that the MIT licence does not answer. The MIT licence covers this repository's code. It says nothing about Perplexity's terms of service or Emailnator's, and automating account creation to bypass query limits is the kind of use that platforms tend to prohibit. That is a decision for you and, if relevant, your counsel; the repository's SECURITY.md is about reporting vulnerabilities, not about this.

Maintenance status, versioning and upgrade cost

The repository is not archived, and the last push was on 2026-09-08. No releases were retrieved, so there is no tagged version history to inspect beyond the version string in pyproject.toml, which reads 0.2.0. The classifier in the same file is "Development Status :: 4 - Beta," and the README's feature list advertises retry logic with exponential backoff and built-in rate limiting, which suggests the authors expect the upstream interface to fail intermittently.

Upgrade cost is hard to estimate from the repository alone. The README points to docs/CHANGELOG.md for "bug fixes and changes history" and docs/IMPROVEMENTS.md for "suggested improvements and roadmap," so those two files are where you would look before bumping a pinned dependency. The declared floor is requires-python >=3.10, with classifiers for 3.10, 3.11 and 3.12, and the README's badge says python-3.10+.

The dependency surface is small: curl_cffi and websocket-client for the core, with patchright, playwright and mcp behind extras. That keeps the blast radius of an upgrade narrow, but curl_cffi is the component that does the browser impersonation, so a change there is the one most likely to break requests against the web interface. Pin it deliberately.

Alternatives and when this is the wrong tool

The obvious alternative is the official @perplexity-ai/mcp-server, and the difference is architectural rather than cosmetic. The official server talks to Perplexity's supported API with an API key, so it gets messages arrays, recency and domain filters, context size control, reasoning effort, thinking stripping, and structured results with citations and images. This project talks to the web interface instead, which is why it needs no key and why it cannot offer any of those parameters. If you have budget for the key and need citations, the official server wins on every axis except cost.

A second alternative is simply writing your own client against the documented Perplexity API. That gives you the same structured responses as the official MCP and keeps you off reverse-engineered endpoints entirely, at the price of doing the integration work yourself.

This project is the wrong tool when you need stable structured output, when your compliance rules forbid scraping or automated account creation, when you need filters the README lists as unsupported, or when you cannot tolerate a beta dependency in a production path. It is a reasonable fit for personal automation, experimentation, and local MCP setups where the plain text answer is all you need and the no-API-key constraint is real.

Editorial conclusion

Adopt it if you are a Python developer who wants Perplexity-style search inside Claude Code or a script without paying for an API key, and you can tolerate a beta interface that depends on reverse-engineered endpoints and Emailnator. Do not adopt it for anything where a stable contract matters: the MCP server returns plain text only, has no citation objects, and the project itself is classified as Beta in pyproject.toml. Before writing code against it, check docs/CHANGELOG.md and docs/IMPROVEMENTS.md, confirm the Python version in requires-python (>=3.10), and decide whether you will supply PERPLEXITY_COOKIES or run anonymously in auto mode.

Frequently asked questions

Official sources

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