Perplexity MCP Server

A FastMCP server that integrates with Perplexity's API to provide web search and grounded AI answers.

Features

Three-Tier Research Workflow

1. search - Ground yourself first

   • Find relevant sources before asking questions

   • Returns URLs, titles, and snippets

   • Use this when you don't know about a topic

2. ask - Get AI answers (DEFAULT)

   • AI-synthesized answers with web grounding

   • Uses the sonar model (fast and cost-effective)

   • Includes citations and optional images/related questions

3. ask_more - Dig deeper

   • More comprehensive analysis for complex questions

   • Uses the sonar-pro model (more capable but pricier)

   • Use when ask doesn't provide sufficient depth

Prerequisites

• Python 3.10 or higher

• A Perplexity API key

• uv (recommended) or pip

Local Setup

1. Install Dependencies

Using uv (recommended):

Or using pip:

2. Configure API Key

Copy the example environment file:

Edit .env and add your Perplexity API key:

3. Run the Server

Test the server locally:

Or with the fastmcp CLI:

4. Install in Claude Desktop

Install the server for use with Claude Desktop:

Or manually add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Cloud Deployment (FastMCP Cloud)

Deploy to fastmcp.cloud for easy hosting:

1. Push to GitHub

2. Deploy on FastMCP Cloud

1. Visit fastmcp.cloud

2. Sign in with GitHub

3. Create a new project and connect your repo

4. Configure:

   • Entrypoint: server.py

   • Environment Variables: Add PERPLEXITY_API_KEY

5. Deploy!

Your server will be available at https://your-project-name.fastmcp.app/mcp

FastMCP Cloud automatically:

• ✅ Detects dependencies from pyproject.toml

• ✅ Deploys on every push to main

• ✅ Creates preview deployments for PRs

• ✅ Handles HTTP transport and authentication

Tool Usage Guide

Research Workflow Example

Tool Parameters

search(query, max_results=10, recency=None, domain_filter=None)

• query: Search query string

• max_results: Number of results (default: 10)

• recency: Filter by time - "day", "week", "month", or "year"

• domain_filter: Include/exclude domains

  • Include: ["wikipedia.org", "github.com"]

  • Exclude: ["-reddit.com", "-pinterest.com"]

ask(query, reasoning_effort="medium", ...)

• query: Question to ask

• reasoning_effort: "low", "medium" (default), or "high"

• search_mode: "web" (default), "academic", or "sec"

• recency: Time filter

• domain_filter: Domain filter

• return_images: Include images (default: False)

• return_related_questions: Include follow-up questions (default: False)

ask_more(query, reasoning_effort="medium", ...)

Same parameters as ask(), but uses the more powerful sonar-pro model.

Cost Optimization

• Start with : Free/cheap way to find sources

• Default to : Uses sonar (cost-effective)

• Escalate to : Only when needed (more expensive)

Development

Project Structure

Inspect the Server

See what FastMCP Cloud will see:

API Reference

This server uses two Perplexity API endpoints:

• Search API (/search) - Returns ranked search results

• Chat Completions API (/chat/completions) - Returns AI-generated answers

Supported models:

• sonar - Fast, cost-effective

• sonar-pro - More comprehensive

Troubleshooting

API Key Issues

If you get authentication errors:

1. Verify your API key at https://www.perplexity.ai/settings/api

2. Check that PERPLEXITY_API_KEY is set correctly

3. Make sure there are no extra spaces or quotes

Timeout Errors

If requests timeout:

• The default timeout is 30s for search, 60s for chat

• Complex questions may take longer

• Consider using reasoning_effort="low" for faster responses

Local Testing

Test individual tools:

This opens an interactive development interface.

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Links

• Perplexity API Docs

• FastMCP Docs

• FastMCP Cloud