How jsonallen/perplexity-mcp works
Project type and purpose
• This is a small, single-service MCP (Model Context Protocol) server written in Python.
• Its purpose is to expose one “tool” (perplexity_search_web) via the MCP protocol so that Claude Desktop (or Cursor) can call it. Under the hood, it forwards queries to Perplexity AI’s HTTP API and returns results.
File structure
• Top‐level files:
• Dockerfile / smithery.yaml – deployment/config metadata
• pyproject.toml – Python packaging and dependencies
• README.md – describes the server’s function and integration points
• src/perplexity_mcp/server.py – the only runtime code, implementing an MCP‐compatible HTTP or IPC server
README for additional insights
• The server registers one prompt/tool (perplexity_search_web).
• It reads environment variables (PERPLEXITY_API_KEY, PERPLEXITY_MODEL).
• It integrates via two clients: Cursor (desktop) and Claude Desktop, both speaking MCP JSON over a local command or HTTP endpoint.
• Installation via Smithery/uv shows how it’s launched (uvx perplexity-mcp).
Main components
a. Client(s)
• Claude Desktop (or Cursor) – initiates an MCP request
• Configuration file (cursor_mcp.json or claude_desktop_config.json) – holds env vars and launch command
b. MCP Server
• Python process (server.py)
• Reads env vars, listens for MCP JSON calls on stdin/stdout or HTTP port
• Uses uvx/uv as the entrypoint
c. External Service
• Perplexity AI HTTP API – receives search queries with API key, returns JSON results
d. Optional Deployment
• Docker container / smithery-managed deployment
Relationships and data flow
1. Client loads config → spawns uvx perplexity-mcp process
2. Claude/ Cursor sends a JSON‐RPC tool call (perplexity_search_web) to server
3. Server parses arguments (query + recency) and env vars
4. Server issues HTTPS request to Perplexity API with API key
5. Perplexity responds with search results
6. Server wraps results in MCP response JSON, returns to client
7. Client displays results in the chat UI
Architectural patterns and design principles
• Plugin-style microservice: the server is a standalone process that plugs into multiple clients
• 12-factor config: uses environment variables for credentials and model choice
• Minimal surface area: only one tool, one endpoint, no persisted state
• Clear separation between protocol (MCP), business logic (Perplexity API wrapper), and deployment
Relevant technologies, frameworks, and libraries
• Python 3.x
• uv/uvx – fast Python package runner
• HTTP(S) + JSON for external API calls
• MCP JSON over stdio or HTTP for client integration
• Docker (optional)
• Smithery (optional CLI installer)
• Component is labeled
• How configuration flows into the server (env vars)
• That server.py is the core implementation