perplexity-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies
pip install -r requirements.txt

# Run the MCP server (stdio transport)
python mcp_server.py

# Export cookies via Playwright (opens browser, log in manually)
pip install playwright
playwright install chromium
python get_cookies.py

# List stored cookie names (without values)
python get_cookies.py --load

# Test with MCP inspector
npx @modelcontextprotocol/inspector python mcp_server.py

# Git workflow (cookie credentials are gitignored)
git status
git add .
git commit -m "message"
git push origin main

Project Structure & Architecture

This is a thin MCP server that wraps Perplexity AI's private internal SSE API, using curl_cffi with Chrome TLS impersonation to bypass Cloudflare.

mcp_server.py            — MCP tool definitions (stdio transport)
    ↑ perplexity_client.py   — HTTP client, SSE parsing, model mapping, payload building
    ↑ cookie_loader.py       — Cookie loading from env var / JSON / HAR / Netscape files
    (get_cookies.py)         — Optional: export cookies via Playwright

Module roles

• mcp_server.py — Entry point. Registers 5 MCP tools (perplexity_ask, perplexity_search, list_models, reset_conversation, set_cookies). Maintains per-session client/conversation state in module-level dicts. Runs via stdio_server().

• perplexity_client.py — Core logic. Contains PerplexityClient (HTTP + SSE), PerplexityConversation (multi-turn state), MODEL_MAP (~30 model name translations), and SSE block parsing (markdown_block, diff_block with chunked streaming, sources_answer_mode, media_items, follow-up suggestions). Exposes set_cookies() for runtime cookie updates.

• cookie_loader.py — Cookie resolution: env var (PERPLEXITY_COOKIES_JSON) > JSON file > HAR file > Netscape-format .txt. Also handles the cookies/perplexity.har path. Exposes parse_cookie_string() for auto-detecting JSON vs Netscape format, used by the set_cookies MCP tool.