perplexity-mcp-server

Self-healing MCP bridge for Perplexity. It connects Claude Code to a local perplexity-api-simple proxy on 127.0.0.1:8765, retries empty responses, publishes health checks through atlas-daily-run, and can optionally install a PostToolUse watchdog hook plus a user-level systemd timer.

What v3.0.0 ships

• Startup health checks plus proxy bootstrap hints.
• Per-call retry and structured MCP errors for empty, unreachable, or rate-limited responses.
• atlas-daily-run for daily health publication to Discord webhook, ntfy, and local logs.
• PostToolUse empty-detector hook, installable from this repo.
• Opt-in auto-repair spawn logic with flap protection.
• Interactive installer prompts for the hook and timer when run from a real terminal.

Tools

| Tool | Model | Use case | |------|-------|----------| | perplexity_ask | sonar-pro | General Q&A, fact-checking, detailed explanations | | perplexity_search | sonar | Quick web search, current events, fast lookups | | perplexity_reason | sonar-reasoning-pro | Architecture decisions, multi-step logic, trade-offs | | perplexity_research | sonar-deep-research | Comprehensive multi-source analysis | | perplexity_batch | mixed | Up to 10 parallel queries with per-query mode selection | | perplexity_pro_search | sonar-pro | Backward-compatible alias for perplexity_ask |

Prerequisites

• Node.js 18+
• claude CLI
• git, curl, and npm
• A local perplexity-api-simple proxy running on http://127.0.0.1:8765
• GitHub auth for this private repo via gh auth login, GITHUB_TOKEN, or SSH

No Perplexity API key is required when the local proxy is using your browser session cookie.

Self-serve install (atlas-ai.au accounts)

After you generate a ppx_ key on your atlas-ai.au account, one command installs and configures the MCP for both claude and codex, pointed at the live VPS proxy (https://ppx.atlas-ai.au):

# The install endpoint bakes your key into the served script as
# PERPLEXITY_PROXY_API_KEY, so it never lands in argv / the process list /
# shell history:
curl -fsSL "https://atlas-ai.au/api/account/perplexity/install?t=<one-time>" | bash

What it does:

1. Writes your key to ${XDG_CONFIG_HOME:-~/.config}/perplexity-api-free/config.toml (proxy_url + proxy_api_key), chmod 600 (dir chmod 700). The key lives only in this file — never in the claude/codex registration command.
2. claude mcp add -s user perplexity-api-free -e PERPLEXITY_API_BASE_URL=https://ppx.atlas-ai.au -- node <dir>/index.js
3. Registers codex via codex mcp add (or merges ~/.codex/config.toml [mcp_servers.perplexity-api-free] without touching other servers; skipped cleanly if codex is absent).
4. Smoke-tests GET /health with your bearer and runs an MCP handshake.

Key intake is env or stdin only (never a CLI argument):

PERPLEXITY_PROXY_API_KEY=ppx_xxx bash install.sh   # env
printf '%s' "$KEY" | bash install.sh --key-stdin   # stdin

Overridable: --proxy-url, --mcp-dir / MCP_DIR, --mcp-repo / MCP_REPO, --scope.

Distribution follow-up (W6 — install endpoint): the default MCP_REPO is a private GitHub repo, so cloning needs gh/GITHUB_TOKEN/SSH. For arbitrary public users the MCP code must be publicly fetchable. install.sh already supports "code already present" (--mcp-dir with an index.js) and a parameterised --mcp-repo, so the install endpoint can serve the code as a public npm package, a public mirror, or a tarball — that channel choice is W6's to make and is not blocked by the installer.

Quick install

Install from GitHub with gh

gh api repos/anombyte93/perplexity-mcp-server/contents/install.sh \
  -H "Accept: application/vnd.github.raw" | bash

Install with curl and GITHUB_TOKEN

curl -fsSL \
  -H "Authorization: token ${GITHUB_TOKEN}" \
  -H "Accept: application/vnd.github.raw" \
  "https://api.github.com/repos/anombyte93/perplexity-mcp-server/contents/install.sh" \
  | bash

Install from a local clone

git clone [email protected]:anombyte93/perplexity-mcp-server.git
cd perplexity-mcp-server
bash install.sh --project-dir /path/to/project

If install.sh is running interactively, it will ask whether to:

• install the PostToolUse empty-detector hook into ~/.claude/settings.json
• install the atlas-daily-run user systemd timer

Non-interactive installs stay conservative and skip both prompts.

What the installer does

1. Verifies node, npm, git, curl, and claude.
2. Authenticates to GitHub and clones the repo into <project>/.mcp/perplexity-api-free.
3. Runs npm install --production.
4. Registers perplexity-api-free with Claude Code over stdio.
5. Verifies the MCP handshake and checks proxy health.
6. Optionally installs the hook and timer when you approve the prompts.

The installer is idempotent. Re-running it updates the checkout to origin/main.

Manual install

mkdir -p /path/to/project/.mcp
git clone --depth 1 https://github.com/anombyte93/perplexity-mcp-server.git \
  /path/to/project/.mcp/perplexity-api-free

npm install --prefix /path/to/project/.mcp/perplexity-api-free --production

claude mcp add -s local --transport stdio \
  -e PERPLEXITY_API_BASE_URL=http://127.0.0.1:8765 \
  perplexity-api-free \
  -- node /path/to/project/.mcp/perplexity-api-free/index.js

atlas-daily-run

atlas-daily-run is the operational wrapper around the MCP server. It runs the same health checks outside Claude Code and publishes a summary.

Examples:

node scripts/atlas-daily-run.js --once
node scripts/atlas-daily-run.js --dry-run
node scripts/atlas-daily-run.js install-claude-hook
node scripts/atlas-daily-run.js --install-systemd

Default behavior:

• WORKING and TRANSIENT exit 0
• DEGRADED exits 2
• BROKEN and UNREACHABLE exit 3

Delivery targets:

• Discord webhook via discord_webhook_url
• ntfy via ntfy_url and ntfy_topic
• local audit log at ~/.local/state/perplexity-api-free/atlas-daily-run.log

PostToolUse hook

The repo ships claude/hooks/perplexity-empty-detector.sh plus a Python installer. The hook watches mcp__perplexity-api-free__* calls for:

• empty responses
• sub-50 byte responses
• "No answer received" style failures

On detection it logs the event, emits a desktop notification when notify-send exists, and adds hook context back into Claude Code without blocking execution.

Install later:

node scripts/atlas-daily-run.js install-claude-hook

Uninstall:

node scripts/atlas-daily-run.js uninstall-claude-hook

Opt-in auto-repair

Auto-repair is disabled by default. When enabled, atlas-daily-run can spawn a repair session after a BROKEN or UNREACHABLE result, protected by a cooldown window so it does not flap.

Config knobs live in config.example.toml:

auto_repair_enabled = true
auto_repair_spawner = "tmux-direct"
auto_repair_flap_protection_hours = 6

One-shot force enable:

node scripts/atlas-daily-run.js --once --auto-repair

Spawner modes:

• tmux-direct creates a detached tmux session running claude
• atlas-launcher is supported as a best-effort path, but not required

State is persisted in ~/.local/state/perplexity-api-free/last-fix-spawn.json.

Configuration

Copy the example file if you want persistent config instead of environment variables:

mkdir -p ~/.config/perplexity-api-free
cp config.example.toml ~/.config/perplexity-api-free/config.toml

Common keys:

| Key | Purpose | |-----|---------| | proxy_url | Override the local proxy URL | | proxy_dir | Optional proxy checkout used for bootstrap hints | | discord_webhook_url | Daily-run Discord delivery | | ntfy_url / ntfy_topic | Push notification fallback | | auto_repair_* | Enable and tune the repair spawner |

Environment variables win over config.toml.

Development

npm test
node index.js

Tests use Node's built-in test runner and stay offline.

Troubleshooting

If searches fail:

1. Check the proxy: curl -sf http://127.0.0.1:8765/health
2. Refresh your Perplexity browser cookie if it expired
3. Re-run the installer if Claude registration drifted
4. Run node scripts/atlas-daily-run.js --once for a structured diagnosis

If the proxy is healthy but Claude still gets empty responses, install the PostToolUse hook so failures become visible in-band instead of silently degrading research quality.

Follow-ups tracked after v3.0.0

• Upstream multi-tunnel rotation remains a proxy-side concern and belongs in perplexity-api-simple, not this repo.
• Daily-run can grow into a multi-check framework beyond Perplexity.
• Auto-repair currently targets detached claude sessions; richer launcher integrations can be added later.
• Installer UX can grow a config bootstrap path for webhook setup if the current prompts are not enough.