Perplexity Skill (Claude Code + Codex)

Use Perplexity web search from either:

• OpenRouter (OPENROUTER_API_KEY)
• Perplexity direct (PERPLEXITY_API_KEY)

This project includes:

• A reusable agent skill: SKILL.md
• A local MCP server: mcp-server/
• Tools:
  • perplexity_search
  • perplexity_ask
  • perplexity_deep_research
  • perplexity_status

Why this exists

• Better web search/research tooling for AI coding agents
• Works in both Claude Code and Codex
• OpenClaw-inspired provider/key/base-url resolution logic

Requirements

• Node.js 22+
• npm
• One API key:
  • OPENROUTER_API_KEY (recommended for OpenRouter routing)
  • or PERPLEXITY_API_KEY (direct Perplexity)

Install

cd /Users/tuyenhx/Workspace/skills/perplexity/mcp-server
npm install

Configure API key

Option A: Environment variables

export OPENROUTER_API_KEY="sk-or-..."
# or
export PERPLEXITY_API_KEY="pplx-..."

Optional model overrides:

export PERPLEXITY_SEARCH_MODEL="perplexity/sonar-pro"
export PERPLEXITY_DEEP_RESEARCH_MODEL="perplexity/sonar-deep-research"

Option B: Config file

mkdir -p ~/.config/perplexity-mcp
cp /Users/tuyenhx/Workspace/skills/perplexity/mcp-server/config.example.json ~/.config/perplexity-mcp/config.json

Then edit ~/.config/perplexity-mcp/config.json with your API key.

Validate locally

node /Users/tuyenhx/Workspace/skills/perplexity/mcp-server/server.mjs --doctor
cd /Users/tuyenhx/Workspace/skills/perplexity/mcp-server
npm run smoke

Register MCP in Codex

codex mcp add perplexity -- node /Users/tuyenhx/Workspace/skills/perplexity/mcp-server/server.mjs

Or edit ~/.codex/config.toml:

[mcp_servers.perplexity]
command = "node"
args = ["/Users/tuyenhx/Workspace/skills/perplexity/mcp-server/server.mjs"]

Register MCP in Claude Code

claude mcp add -s user perplexity -- node /Users/tuyenhx/Workspace/skills/perplexity/mcp-server/server.mjs

Link skill

ln -sfn /Users/tuyenhx/Workspace/skills/perplexity ~/.claude/skills/perplexity
ln -sfn /Users/tuyenhx/Workspace/skills/perplexity ~/.codex/skills/perplexity

Restart Claude/Codex sessions after changing MCP/skills.

Project layout

perplexity/
├── SKILL.md
├── README.md
└── mcp-server/
    ├── server.mjs
    ├── smoke-test.mjs
    ├── package.json
    ├── package-lock.json
    ├── config.example.json
    └── README.md

Notes

• perplexity_research is intentionally not used by this skill policy.
• Deep research should use perplexity_deep_research when available.