https://github.com/jschuller/perplexity-mcp
An enhanced MCP server for Perplexity AI that allows Claude Desktop and other MCP clients to search the web using Perplexity's powerful API. This server implements the full range of Perplexity API parameters, providing fine-grained control over search behavior and response generation.
https://github.com/jschuller/perplexity-mcp
Last synced: 4 months ago
JSON representation
An enhanced MCP server for Perplexity AI that allows Claude Desktop and other MCP clients to search the web using Perplexity's powerful API. This server implements the full range of Perplexity API parameters, providing fine-grained control over search behavior and response generation.
- Host: GitHub
- URL: https://github.com/jschuller/perplexity-mcp
- Owner: jschuller
- License: mit
- Created: 2025-05-03T11:28:22.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-24T23:04:36.000Z (4 months ago)
- Last Synced: 2026-03-26T03:54:51.252Z (4 months ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@jschuller/perplexity-mcp
- Size: 70.3 KB
- Stars: 6
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
Perplexity MCP Server
Search the web from Claude Desktop, Claude Code, or any MCP client using Perplexity AI —
with fine-grained control over recency, citations, images, and model parameters.
---
## What This Does
This MCP server connects AI assistants to [Perplexity AI](https://www.perplexity.ai/)'s search API. Ask questions in natural language and get grounded, cited answers from the live web — directly inside Claude or any MCP-compatible client.
**One tool, full control:** `perplexity_search_web` exposes the complete Perplexity API — recency filtering, model selection, temperature, top_k/top_p, citation/image toggles, and streaming.
## Getting Started
### 1. Get a Perplexity API Key
Sign up at [perplexity.ai](https://www.perplexity.ai/) and generate an API key from your [account settings](https://www.perplexity.ai/settings/api).
### 2. Install & Configure
#### Claude Code (Recommended)
```bash
claude mcp add perplexity -- npx -y @jschuller/perplexity-mcp
```
Then set your API key:
```bash
export PERPLEXITY_API_KEY=pplx-your-key-here
```
#### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"perplexity": {
"command": "npx",
"args": ["-y", "@jschuller/perplexity-mcp"],
"env": {
"PERPLEXITY_API_KEY": "pplx-your-key-here"
}
}
}
}
```
Config location:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
#### From Source
```bash
git clone https://github.com/jschuller/perplexity-mcp.git
cd perplexity-mcp
npm install && npm run build
```
### 3. Verify
Ask Claude: *"Search the web for the latest developments in quantum computing from the last week"*
## Tool Reference
### `perplexity_search_web`
| Parameter | Type | Default | Description |
|---|---|---|---|
| **`query`** | string | *(required)* | Search query |
| `recency` | `day` \| `week` \| `month` \| `year` | `month` | Filter results by time period |
| `model` | string | `sonar` | Perplexity model ([model cards](https://docs.perplexity.ai/guides/model-cards)) |
| `temperature` | number | — | Randomness (0 = deterministic, 2 = creative) |
| `max_tokens` | integer | — | Maximum tokens to generate |
| `top_k` | integer | — | Limit high-probability token pool (0 = disable) |
| `top_p` | number | — | Nucleus sampling threshold |
| `frequency_penalty` | number | — | Penalize repeated tokens |
| `presence_penalty` | number | — | Encourage topic variety |
| `return_citations` | boolean | `true` | Include source citations |
| `return_images` | boolean | `false` | Include relevant images |
| `stream` | boolean | `false` | Stream response incrementally |
## Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| `PERPLEXITY_API_KEY` | Yes | — | Your Perplexity API key |
| `PERPLEXITY_MODEL` | No | `sonar` | Default model for all queries |
## Available Models
- **`sonar`** — Standard model (default)
- **`sonar-pro`** — Enhanced capabilities
- See full list: [Perplexity Model Cards](https://docs.perplexity.ai/guides/model-cards)
## Security
- API key stays in your local environment — never sent anywhere except the Perplexity API
- The server communicates only with `api.perplexity.ai` over HTTPS
- No data is stored or logged beyond the API request lifecycle
- See [SECURITY.md](SECURITY.md) for vulnerability reporting
## Troubleshooting
| Issue | Fix |
|---|---|
| `PERPLEXITY_API_KEY is required` | Set the env var in your MCP client config or shell |
| `400 invalid_request_error` | Update to v2.1.0+ (fixes JSON Schema validation with Claude Code) |
| Server not found | Verify `npx @jschuller/perplexity-mcp` runs without error |
| Connection timeout | Check internet connectivity and [Perplexity API status](https://status.perplexity.ai/) |
## Contributing
Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
## License
MIT