MCP Perplexity Pro

An MCP server for the Perplexity API, written in Python (FastMCP, SQLAlchemy, SQLite). It serves MCP over stdio or Streamable HTTP and keeps its own data in a local SQLite database.

Status: 2.0.0

Version 2.0.0 replaces the TypeScript 1.x server. The reason is that Perplexity retired the Sonar endpoints the 1.x server called: both POST /chat/completions and GET /async/chat/completions now return 403 chat_completions_not_available ("Sonar is now the Agent API"), so 1.x could not answer a single query. There was no working behavior to port, so the TypeScript code is deleted (git history keeps it) and the server was rebuilt in Python on the Agent API (POST /v1/agent).

Eleven tools exist today:

| Tool | What it does | Spends money | |---|---|---| | perplexity_ask | One web-grounded question, answered synchronously with its sources. The routing mode picks the model (default perplexity/sonar); or a depth (fast, low, medium), a tier or a model | yes | | perplexity_chat | A multi-turn conversation kept in the local database: send, list, read, delete | send only | | perplexity_research | Starts a deep research run in the background and returns a job id at once. Depth medium (default), high or xhigh | yes, when a call observes the run finish | | perplexity_jobs | Manages research runs: list, status, result, cancel | no new spend; it records the finished run's | | perplexity_search | Ranked web search results as data (title, url, snippet, dates), with no model answer. Type fast (default, $0.001 per request) or web ($0.005 per request) | yes | | perplexity_decide | Typed questions about a text, answered with calibrated probabilities: a yes probability, the most probable option, or a position on an ordered rubric. One request holds up to 32 questions. About $0.02 per million input tokens, output free | yes | | perplexity_embed | Indexes saved chats, completed research reports or texts you pass as vectors in the local database, and searches them by meaning: index, search, status, delete. index sends the text to Perplexity. $0.004 (pplx-embed-v1-0.6b) or $0.03 (pplx-embed-v1-4b) per million tokens | index and search | | perplexity_models | Lists the models your key can use, with live prices and accepted effort levels from the model matrix, plus the documented Agent API presets | no | | perplexity_projects | Lists projects, or deletes one and its stored records (spend history is kept) | no | | perplexity_usage | Reports what recorded upstream calls cost, grouped by tool, API, model, project or day. Read-only | no | | perplexity_help | The server's own help: an index that picks the right tool, one tool's page, or a topic. Free, no API call | no |

The four Agent tools, perplexity_search, perplexity_decide and perplexity_embed record their usage. Every costed upstream call stores one usage event (perplexity_usage reports them), and a background research run is recorded once, by the first perplexity_jobs call that sees it finish.

These tools can spend money, and there is no cost ceiling. A nameless ask or chat uses the routing default, perplexity/sonar, which cost more than the fast depth in the one pair measured (see "Choosing how models are picked"); research defaults to medium and search to its cheaper type (fast). high and xhigh exist only behind perplexity_research because a single run can cost dollars (see "Cost by depth").

The old tool names (ask_perplexity, chat_perplexity and the rest) are gone and are not coming back under those names. No data is imported from 1.x.

Install and run

Requires Python 3.12 or newer and uv.

git clone <this repository> && cd mcp-perplexity-pro
uv sync
export PERPLEXITY_API_KEY=<your-perplexity-api-key>

From PyPI (2.0.0 and later), with nothing cloned:

export PERPLEXITY_API_KEY=<your-perplexity-api-key>

# run the MCP server (stdio is the default transport)
uvx mcp-perplexity-pro

# run the command line
uvx --from mcp-perplexity-pro perplexity-pro ask "What is new in Python?"

# or install both commands once
uv tool install mcp-perplexity-pro        # then: mcp-perplexity-pro, perplexity-pro
pipx install mcp-perplexity-pro

How a release is made: docs/releasing.md.

Start commands from a checkout:

# stdio (the default transport): the MCP client launches this process
uv run mcp-perplexity-pro --transport stdio

# Streamable HTTP on http://127.0.0.1:8102/mcp (health: http://127.0.0.1:8102/health)
uv run mcp-perplexity-pro --transport http

# without a checkout-managed environment
uvx --from . mcp-perplexity-pro --transport http

# check the install
uv run mcp-perplexity-pro --version
uv run mcp-perplexity-pro --help

# the command line front end (see "Command line")
uv run perplexity-pro --help

In stdio mode stdout carries only MCP messages; every log line goes to stderr. A missing or invalid setting prints a message naming the variable and exits with status 1 before anything is created on disk or any port is opened.

Run under pm2

The supervised setup is one pm2 app that runs the HTTP transport on port 8102. Copy the example configuration, set your key in the copy, and start it. The copy is gitignored so the key never enters the repository:

cp ecosystem.example.cjs ecosystem.config.cjs   # then replace REPLACE_ME with your key
pm2 start ecosystem.config.cjs
curl -s http://127.0.0.1:8102/health            # {"status":"ok","version":"2.0.0"}

kill_timeout is 15000 ms because on SIGTERM or SIGINT the server finishes in-flight calls for up to 10 seconds, closes its HTTP client and database connections, and exits 0; pm2 must wait longer than that before it sends SIGKILL. pm2 restart mcp-perplexity-pro brings the server back on the same port.

Command line

The same tools are a command line, perplexity-pro, for a person or a script that would rather not run an MCP client. mcp-perplexity-pro is unchanged (it is still what pm2 and every MCP client configuration start); perplexity-pro serve runs the same server.

uv run perplexity-pro ask "What is new in Python?" --depth fast
uv run perplexity-pro search "rust borrow checker" "zig comptime" --domains=-reddit.com
uv run perplexity-pro chat send --title notes --message "Remember: teal."
uv run perplexity-pro models --json | jq '.routing'
uv run perplexity-pro usage --group-by tool
uv run perplexity-pro help            # the index; `help ask`, `help costs`, `help topic projects`
uv run perplexity-pro serve --transport http

Every command calls the registered tool in-process, so routing, validation, project rules, usage recording and error categories are exactly the MCP tool's, and a costed command records one usage event in the same database. The subcommands (ask, chat, research, jobs, search, decide, embed, models, projects, usage, help, serve) and their flags are generated from the tool schemas, so a new tool parameter appears as a flag without an edit.

| Rule | Form | |---|---| | Positionals | a required action, then a required query (ask "q", chat send, jobs status); everything else is a --flag with dashes (--max-results 3) | | Booleans | --search and --no-search; unset means the tool's default | | Lists | repeat the flag: --domains python.org --domains docs.python.org; a search takes several queries as positionals | | Objects and arrays | JSON: --json-schema '{...}', --json-schema @schema.json or --json-schema - (standard input, once); an untyped value such as decide's --state is JSON when it is an object or array and text otherwise | | Anything else | --args-json '{"query": "q", "depth": "low"}' (JSON, @file or -), merged first; flags win; a JSON null means not given | | A value that starts with a dash | --domains=-reddit.com, and -- before a query that starts with one |

Output is the tool's readable text on standard output, or the structured result with --json. Exit status: 0 on success, 1 for a tool error (standard error shows [category] message, ending with Run perplexity-pro help <command> for its arguments and examples.) or a setup failure (missing key, invalid setting), 2 for a usage error (a wrong type, an unknown or abbreviated flag, a value outside a schema enum, a missing required value) refused before anything is set up or sent, 130 for Ctrl-C. A described value the schema does not list as an enum (a depth, a tier) reaches the tool, which refuses it as a tool error. Logs are warnings and errors only unless PERPLEXITY_LOG_LEVEL is set, and stay on standard error. --help, <command> --help, help and --version need no key, no network and no data directory, and survive an invalid environment (the routing line then shows the defaults, with one warning). help projects is the tool page, help topic projects the topic. Live record: openspec/changes/archive/2026-10-13-py-cli/acceptance/ (two billed asks, $0.00723, reconciled to the nano-USD).

Settings

All settings are environment variables with the prefix PERPLEXITY_. They are validated at startup; an invalid value aborts startup with a message naming the variable and the offending value. No .env file is read.

| Variable | Default | Meaning | |---|---|---| | PERPLEXITY_API_KEY | none, required | The Perplexity API key. Never logged, returned or stored on disk | | PERPLEXITY_HOST | 127.0.0.1 | HTTP bind host. A non-loopback value logs a startup warning (see Security) | | PERPLEXITY_PORT | 8102 | HTTP port, 1 to 65535 | | PERPLEXITY_BASE_URL | https://api.perplexity.ai | Perplexity API base URL (http or https) | | PERPLEXITY_DATA_DIR | ~/.perplexity-pro/ | Where the SQLite database, migration lock and backups live | | PERPLEXITY_LOG_LEVEL | INFO | DEBUG, INFO, WARNING, ERROR or CRITICAL (case-insensitive) | | PERPLEXITY_CONNECT_TIMEOUT | 10 | Seconds to establish a connection to the API | | PERPLEXITY_READ_TIMEOUT | 60 | Seconds to wait for the API's response | | PERPLEXITY_AGENT_READ_TIMEOUT | 120 | Seconds to wait for a synchronous Agent run (perplexity_ask, perplexity_chat send). A background submit and every other request use PERPLEXITY_READ_TIMEOUT. Must be greater than 0 | | PERPLEXITY_MAX_ATTEMPTS | 3 | Attempts per API request (HTTP 429 is retried honoring Retry-After; GET requests are also retried on 5xx, timeouts and connection failures; a create POST is retried only after a connect failure) | | PERPLEXITY_MAX_RETRY_WAIT | 30 | Longest wait in seconds between attempts; a Retry-After longer than this is not waited out | | PERPLEXITY_CATALOG_TTL | 3600 | Seconds the model list is cached | | PERPLEXITY_CATALOG_MAX_STALE | 86400 | Oldest cached model list, in seconds, that may be returned when the live request fails | | PERPLEXITY_DB_BUSY_TIMEOUT | 5 | Seconds a write waits for the database lock before failing with storage_busy | | PERPLEXITY_ROUTING | standard | standard, custom or dynamic, case-insensitive. See "Choosing how models are picked" | | PERPLEXITY_MODEL | perplexity/sonar | standard mode: the model a call that names nothing uses; dynamic mode: the standard tier's model | | PERPLEXITY_CLASSIFIER | rules | dynamic mode only: rules (fixed offline rules) or decisions (the Decisions API picks the tier, the rules back it up). Ignored with a warning in other modes | | PERPLEXITY_MATRIX_REFRESH | 86400 | Seconds between refreshes of the model matrix (see "Model matrix"); 0 refreshes only at start, otherwise 300 to 604800 | | PERPLEXITY_MATRIX_PROBE | new | new probes models neither the matrix file nor the packaged baseline knows (a few cents at most p