Perplexity MCP Server

Python MCP server that exposes Perplexity Sonar Chat Completions to any MCP client (Cursor, Claude Desktop, custom agents).

Tools

Both tools accept optional Sonar parameters and return JSON:

{
  "answer": "...",
  "citations": ["https://..."],
  "search_results": [],
  "model": "sonar-pro",
  "usage": {}
}

Optional parameters

Prefer date filters over search_recency_filter when the window is known exactly. Queries are capped at 4,000 characters. The API key is never logged or returned in tool output.

Related MCP server: Perplexity Web-Search MCP

Setup

1. Copy env template and add your Perplexity API key:

cp .env.example .env

2. Install with uv:

uv sync

Run locally (stdio)

uv run mcp-perplexity

Cursor / Claude Desktop

Add to your MCP config (adjust the project path):

{
  "mcpServers": {
    "perplexity": {
      "command": "uv",
      "args": ["--directory", "C:/Users/KozakJ/git/mcp_perplexity", "run", "mcp-perplexity"],
      "env": {
        "PERPLEXITY_API_KEY": "pplx-your-api-key-here"
      }
    }
  }
}

Or rely on a .env file in the project directory (PERPLEXITY_API_KEY=...).

Cursor / Claude Desktop (container, stdio)

Rebuild after image changes, then only the API key is required — other settings use the same defaults as local runs:

{
  "mcpServers": {
    "perplexity": {
      "command": "podman",
      "args": [
        "run", "-i", "--rm",
        "-e", "PERPLEXITY_API_KEY",
        "mcp-perplexity"
      ],
      "env": {
        "PERPLEXITY_API_KEY": "pplx-your-api-key-here"
      }
    }
  }
}

Override any setting the same way (-e MCP_PORT, etc.) only when you need non-defaults.

Run with Podman (streamable HTTP)

podman compose needs a compose provider (podman-compose or Docker Compose). On a plain Podman install, use build + run:

podman build -t mcp-perplexity .
podman run --rm -p 8000:8000 --env-file .env ^
  -e MCP_TRANSPORT=streamable-http ^
  -e MCP_HOST=0.0.0.0 ^
  -e MCP_PORT=8000 ^
  --name mcp-perplexity mcp-perplexity

(On bash/zsh, replace ^ with \.)

If you have a compose provider installed (pip install podman-compose, or Docker Compose):

podman compose up --build

Endpoint: http://localhost:8000/mcp (Streamable HTTP). Bind to trusted networks only — this image does not add HTTP auth.

Configuration

Retries use exponential backoff (honors Retry-After when present). Logging goes to stderr only so stdio JSON-RPC stays clean.