Perplexity Research MCP for Claude Desktop

A small, single-file Python MCP server that lets Claude Desktop search the web and run deep research with Perplexity, without hitting Claude Desktop's tool-call timeout.

• Local, nothing to deploy. Claude Desktop starts the server itself over stdio.

• Long research does not time out. Research jobs run in Perplexity's background mode. If a job is not finished within ~45 s, the tool returns a job ID and Claude collects the result later.

• Current Perplexity APIs. Built on the Agent API (presets fast … xhigh) and the Search API, not the legacy Sonar models.

• Answers with numbered sources and the real cost of every query.

• Small and readable. One file (~380 lines), two dependencies (mcp, httpx), tests with a mocked API.

Tools

Costs are rough estimates based on Perplexity pricing (October 2026). The actual cost is appended to every answer.

Search tools support filters: recency (hour … year), domains (allow list, or deny list with a - prefix), after_date / before_date (MM/DD/YYYY). perplexity_web_results also takes languages and country.

Related MCP server: Perplexity MCP Server

How it differs from the official Perplexity MCP server

Perplexity maintains an official server, perplexityai/modelcontextprotocol, plus a hosted remote server. Use the official one if you want a widely used, maintained package. This project is an alternative if you want:

• deep research that survives Claude Desktop's tool-call timeout (background jobs + perplexity_result instead of one long call),

• a short Python codebase you can read in a few minutes and adapt,

• the query cost shown in every answer.

Setup

Requirements: Python 3.10+, Claude Desktop, a Perplexity API key.

1. Install

git clone https://github.com/<your-account>/perplexity-research-mcp.git
cd perplexity-research-mcp
python -m venv .venv

macOS / Linux:

.venv/bin/pip install -r requirements.txt

Windows (PowerShell):

.venv\Scripts\pip install -r requirements.txt

2. Add your API key

Create a key at https://console.perplexity.ai (and add credit). Copy .env.example to .env and fill in the key:

PERPLEXITY_API_KEY=pplx-...

.env is in .gitignore. Never commit it. If the key leaks, revoke it in the console.

3. Register the server in Claude Desktop

Open the config file (Claude Desktop → Settings → Developer → Edit Config):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server with absolute paths to the virtualenv's Python and to server.py.

macOS / Linux:

{
  "mcpServers": {
    "perplexity": {
      "command": "/Users/you/perplexity-research-mcp/.venv/bin/python",
      "args": ["/Users/you/perplexity-research-mcp/server.py"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "perplexity": {
      "command": "C:\\Users\\you\\perplexity-research-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\you\\perplexity-research-mcp\\server.py"]
    }
  }
}

If the file already has an mcpServers section, add the perplexity entry to it.

The key is read from .env next to server.py, so it does not have to be in the Claude config. You can also pass it through "env": {"PERPLEXITY_API_KEY": "..."} in the config instead.

4. Restart Claude Desktop

Quit Claude Desktop completely (including the tray / menu bar icon) and start it again. Under Settings → Developer, the perplexity server should show as running.

Try it

Use perplexity_search with preset fast: what will the weather be in London tomorrow?
List the sources and the query cost.

Use perplexity_research with depth medium: what were the most important EV news of the
last month? If it returns a job ID, collect the result with perplexity_result.

Configuration

Troubleshooting

• The server does not appear: check the absolute paths in the config and restart Claude Desktop fully.

• Logs: mcp-server-perplexity.log in Claude Desktop's log folder (macOS: ~/Library/Logs/Claude/, Windows: %APPDATA%\Claude\logs\). The server never logs the API key or the query text.

• 401: the key is wrong or revoked. 402: add credit. 429: rate limit, try again later.

Development

pip install -r requirements-dev.txt
pytest

The tests mock the Perplexity API with respx, so they make no real calls and cost nothing.

Privacy

Queries are sent to Perplexity and handled under Perplexity's API policies. Nothing is stored locally.

License

MIT