perplexity-mcp: Instructions file for Claude Code

Perplexity MCP Server

Environment

• Virtual environment: .venv/ — always use .venv/bin/python to run scripts
• Install with uv pip install -e . (no pip in venv, use uv)

Setup

uv pip install -e . --python .venv/bin/python

Project Structure

Monorepo — everything in one place:

src/                     # MCP stdio server (thin wrapper)
  server.py              # MCP server entry point, pool state sync, timeout handling
  tools.py               # MCP tool definitions (perplexity_ask, perplexity_research)

perplexity/              # Backend engine
  client.py              # Perplexity API client (curl_cffi, bypasses Cloudflare)
  config.py              # All constants, endpoints, model mappings
  exceptions.py          # Custom exception hierarchy
  logger.py              # Centralized logging
  server/
    app.py               # Starlette app, run_query() with pool rotation + fallback
    client_pool.py        # ClientPool, ClientWrapper, monitor, state persistence
    admin.py              # Admin REST API routes (plain Starlette) + static file serving
    utils.py              # Validation helpers
    main.py               # HTTP server entry point (uvicorn, port 8123)
    web/                  # React admin frontend (Vite + Tailwind)
      src/                # Frontend source
      dist/               # Built frontend (gitignored)

tests/                   # Test suite

Configuration

• Token config: token_pool_config.json (gitignored) — tokens, monitor, fallback settings
• Environment: .env — PERPLEXITY_TIMEOUT (default 900s), PPLX_ADMIN_TOKEN
• The server auto-discovers token_pool_config.json in the working directory

token_pool_config.json schema

{
  "monitor": {
    "enable": false,
    "interval": 6,
    "tg_bot_token": null,
    "tg_chat_id": null
  },
  "fallback": { "fallback_to_auto": true },
  "tokens": [
    { "id": "main", "csrf_token": "...", "session_token": "..." }
  ]
}